openapi: 3.1.0
info:
  title: Brevo Transactional Email API
  description: >-
    The Brevo Transactional Email API allows developers to send transactional
    emails such as order confirmations, password resets, and account
    notifications programmatically. It supports single and batch sending,
    scheduled deliveries, template-based emails, and attachment handling. The
    API also provides endpoints for tracking email activity including opens,
    clicks, bounces, and delivery status through detailed event logs and
    real-time webhooks.
  version: '3.0'
  contact:
    name: Brevo Support
    url: https://help.brevo.com
  termsOfService: https://www.brevo.com/legal/termsofuse/
externalDocs:
  description: Brevo Transactional Email Documentation
  url: https://developers.brevo.com/docs/send-a-transactional-email
servers:
  - url: https://api.brevo.com/v3
    description: Brevo Production API Server
tags:
  - name: Email Activity
    description: >-
      Track and retrieve transactional email activity including delivery
      status, opens, clicks, and bounces.
  - name: Email Templates
    description: >-
      Create and manage reusable email templates for transactional messaging.
  - name: Senders
    description: >-
      Manage sender identities used for transactional email sending.
  - name: Transactional Emails
    description: >-
      Send and manage transactional emails including order confirmations,
      password resets, and account notifications.
security:
  - apiKeyAuth: []
paths:
  /smtp/email:
    post:
      operationId: sendTransactionalEmail
      summary: Send a transactional email
      description: >-
        Sends a transactional email to one or more recipients. Supports
        personalization with dynamic parameters, template-based content,
        attachments, and scheduled delivery. Can also send to multiple
        recipients in a single call.
      tags:
        - Transactional Emails
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendTransactionalEmail'
      responses:
        '201':
          description: Email sent successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendEmailResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /smtp/email/batch:
    post:
      operationId: batchSendTransactionalEmails
      summary: Batch send transactional emails
      description: >-
        Sends multiple transactional emails in a single API call. Each email
        in the batch can have different recipients, content, and parameters.
        Template placeholders can fetch values from the contact database.
      tags:
        - Transactional Emails
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                messageVersions:
                  type: array
                  description: >-
                    List of email messages to send in the batch.
                  items:
                    $ref: '#/components/schemas/SendTransactionalEmail'
      responses:
        '201':
          description: Batch emails sent successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendEmailResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /smtp/statistics/events:
    get:
      operationId: getTransactionalEmailEvents
      summary: Get transactional email activity events
      description: >-
        Retrieves all transactional email activity as unaggregated events.
        Returns individual event records for deliveries, opens, clicks,
        bounces, spam reports, and other email activity.
      tags:
        - Email Activity
      parameters:
        - $ref: '#/components/parameters/limitParam'
        - $ref: '#/components/parameters/offsetParam'
        - name: startDate
          in: query
          description: >-
            Start date for the event query in YYYY-MM-DD format.
          schema:
            type: string
            format: date
        - name: endDate
          in: query
          description: >-
            End date for the event query in YYYY-MM-DD format.
          schema:
            type: string
            format: date
        - name: event
          in: query
          description: >-
            Filter by event type such as delivered, opened, clicked,
            hardBounce, softBounce, blocked, spam, or unsubscribed.
          schema:
            type: string
            enum:
              - sent
              - delivered
              - opened
              - clicked
              - hardBounce
              - softBounce
              - blocked
              - spam
              - invalid
              - deferred
              - unsubscribed
        - name: email
          in: query
          description: >-
            Filter events by recipient email address.
          schema:
            type: string
            format: email
        - name: messageId
          in: query
          description: >-
            Filter events by the unique message identifier.
          schema:
            type: string
        - name: templateId
          in: query
          description: >-
            Filter events by the template ID used for sending.
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: Transactional email events retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailEventReport'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /smtp/statistics/aggregatedReport:
    get:
      operationId: getAggregatedEmailReport
      summary: Get aggregated transactional email statistics
      description: >-
        Retrieves aggregated statistics for transactional email activity over
        a specified period. Returns totals for requests, delivered, opens,
        clicks, bounces, and other metrics.
      tags:
        - Email Activity
      parameters:
        - name: startDate
          in: query
          description: >-
            Start date for the report in YYYY-MM-DD format.
          schema:
            type: string
            format: date
        - name: endDate
          in: query
          description: >-
            End date for the report in YYYY-MM-DD format.
          schema:
            type: string
            format: date
      responses:
        '200':
          description: Aggregated email statistics retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AggregatedEmailReport'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /smtp/templates:
    get:
      operationId: listSmtpTemplates
      summary: List email templates
      description: >-
        Retrieves all transactional email templates created in the account.
        Templates can be used to send personalized transactional emails
        with consistent formatting.
      tags:
        - Email Templates
      parameters:
        - $ref: '#/components/parameters/limitParam'
        - $ref: '#/components/parameters/offsetParam'
        - name: templateStatus
          in: query
          description: >-
            Filter templates by their active status.
          schema:
            type: boolean
      responses:
        '200':
          description: Templates retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TemplateList'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      operationId: createSmtpTemplate
      summary: Create an email template
      description: >-
        Creates a new transactional email template with HTML content,
        subject line, and sender information. Templates support dynamic
        parameters for personalization.
      tags:
        - Email Templates
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSmtpTemplate'
      responses:
        '201':
          description: Template created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateTemplateResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /smtp/templates/{templateId}:
    get:
      operationId: getSmtpTemplate
      summary: Get an email template
      description: >-
        Retrieves the details of a specific transactional email template
        by its unique identifier.
      tags:
        - Email Templates
      parameters:
        - $ref: '#/components/parameters/templateIdParam'
      responses:
        '200':
          description: Template retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SmtpTemplate'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Template not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      operationId: updateSmtpTemplate
      summary: Update an email template
      description: >-
        Updates an existing transactional email template with new content,
        subject line, or sender information.
      tags:
        - Email Templates
      parameters:
        - $ref: '#/components/parameters/templateIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSmtpTemplate'
      responses:
        '204':
          description: Template updated successfully
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Template not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      operationId: deleteSmtpTemplate
      summary: Delete an email template
      description: >-
        Permanently deletes a transactional email template by its unique
        identifier.
      tags:
        - Email Templates
      parameters:
        - $ref: '#/components/parameters/templateIdParam'
      responses:
        '204':
          description: Template deleted successfully
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Template not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /smtp/email/{messageId}:
    get:
      operationId: getTransactionalEmailContent
      summary: Get the content of a sent transactional email
      description: >-
        Retrieves the personalized content of a previously sent transactional
        email including the rendered HTML body, subject line, and recipient
        information.
      tags:
        - Transactional Emails
      parameters:
        - name: messageId
          in: path
          required: true
          description: >-
            The unique message identifier of the sent transactional email.
          schema:
            type: string
      responses:
        '200':
          description: Email content retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionalEmailContent'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Email not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /senders:
    get:
      operationId: getSenders
      summary: Get email senders
      description: >-
        Retrieves the list of all sender identities configured in the
        account for use with transactional and marketing emails.
      tags:
        - Senders
      parameters:
        - name: ip
          in: query
          description: >-
            Filter senders by dedicated IP address.
          schema:
            type: string
        - name: domain
          in: query
          description: >-
            Filter senders by domain name.
          schema:
            type: string
      responses:
        '200':
          description: Senders retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SenderList'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      operationId: createSender
      summary: Create a new sender
      description: >-
        Creates a new sender identity that can be used for sending
        transactional and marketing emails. The sender must be verified
        before use.
      tags:
        - Senders
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSender'
      responses:
        '201':
          description: Sender created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateSenderResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: api-key
      description: >-
        Brevo API key passed in the api-key request header for
        authentication.
  parameters:
    limitParam:
      name: limit
      in: query
      description: >-
        Maximum number of results to return per request.
      schema:
        type: integer
        format: int64
        default: 50
    offsetParam:
      name: offset
      in: query
      description: >-
        Number of results to skip for pagination.
      schema:
        type: integer
        format: int64
        default: 0
    templateIdParam:
      name: templateId
      in: path
      required: true
      description: >-
        The unique identifier of the email template.
      schema:
        type: integer
        format: int64
  schemas:
    SendTransactionalEmail:
      type: object
      required:
        - sender
        - to
      properties:
        sender:
          type: object
          description: >-
            The sender identity for the email.
          properties:
            name:
              type: string
              description: >-
                Display name of the sender.
            email:
              type: string
              format: email
              description: >-
                Email address of the sender.
        to:
          type: array
          description: >-
            List of recipient email addresses and optional names.
          items:
            type: object
            required:
              - email
            properties:
              email:
                type: string
                format: email
                description: >-
                  Recipient email address.
              name:
                type: string
                description: >-
                  Recipient display name.
        cc:
          type: array
          description: >-
            List of CC recipient email addresses.
          items:
            type: object
            properties:
              email:
                type: string
                format: email
                description: >-
                  CC recipient email address.
              name:
                type: string
                description: >-
                  CC recipient display name.
        bcc:
          type: array
          description: >-
            List of BCC recipient email addresses.
          items:
            type: object
            properties:
              email:
                type: string
                format: email
                description: >-
                  BCC recipient email address.
              name:
                type: string
                description: >-
                  BCC recipient display name.
        subject:
          type: string
          description: >-
            Subject line of the email. Required if not using a template.
        htmlContent:
          type: string
          description: >-
            HTML body content of the email. Required if not using a template.
        textContent:
          type: string
          description: >-
            Plain text body content of the email as a fallback.
        templateId:
          type: integer
          format: int64
          description: >-
            ID of the template to use for the email content.
        params:
          type: object
          description: >-
            Dynamic parameters for template personalization as key-value pairs.
          additionalProperties: true
        replyTo:
          type: object
          description: >-
            Reply-to address for the email.
          properties:
            email:
              type: string
              format: email
              description: >-
                Reply-to email address.
            name:
              type: string
              description: >-
                Reply-to display name.
        attachment:
          type: array
          description: >-
            List of file attachments to include with the email.
          items:
            type: object
            properties:
              url:
                type: string
                format: uri
                description: >-
                  URL of the attachment file to download and include.
              content:
                type: string
                description: >-
                  Base64 encoded content of the attachment.
              name:
                type: string
                description: >-
                  Filename of the attachment.
        headers:
          type: object
          description: >-
            Custom email headers as key-value pairs.
          additionalProperties:
            type: string
        tags:
          type: array
          description: >-
            Tags to categorize the email for tracking purposes.
          items:
            type: string
        scheduledAt:
          type: string
          format: date-time
          description: >-
            UTC date-time to schedule the email for future delivery.
    SendEmailResponse:
      type: object
      properties:
        messageId:
          type: string
          description: >-
            Unique identifier assigned to the sent email message.
    EmailEventReport:
      type: object
      properties:
        events:
          type: array
          description: >-
            List of transactional email activity events.
          items:
            type: object
            properties:
              email:
                type: string
                format: email
                description: >-
                  Recipient email address associated with the event.
              date:
                type: string
                format: date-time
                description: >-
                  UTC date-time when the event occurred.
              messageId:
                type: string
                description: >-
                  Unique identifier of the email message.
              event:
                type: string
                description: >-
                  Type of email event that occurred.
                enum:
                  - sent
                  - delivered
                  - opened
                  - clicked
                  - hardBounce
                  - softBounce
                  - blocked
                  - spam
                  - invalid
                  - deferred
                  - unsubscribed
              reason:
                type: string
                description: >-
                  Reason for the event if applicable, such as bounce details.
              tag:
                type: string
                description: >-
                  Tag assigned to the email for categorization.
              subject:
                type: string
                description: >-
                  Subject line of the email message.
              templateId:
                type: integer
                format: int64
                description: >-
                  Template ID used for the email if applicable.
    AggregatedEmailReport:
      type: object
      properties:
        range:
          type: string
          description: >-
            Date range for the aggregated statistics.
        requests:
          type: integer
          format: int64
          description: >-
            Total number of email send requests.
        delivered:
          type: integer
          format: int64
          description: >-
            Total number of successfully delivered emails.
        hardBounces:
          type: integer
          format: int64
          description: >-
            Total number of hard bounces.
        softBounces:
          type: integer
          format: int64
          description: >-
            Total number of soft bounces.
        clicks:
          type: integer
          format: int64
          description: >-
            Total number of link clicks.
        uniqueClicks:
          type: integer
          format: int64
          description: >-
            Total number of unique link clicks.
        opens:
          type: integer
          format: int64
          description: >-
            Total number of email opens.
        uniqueOpens:
          type: integer
          format: int64
          description: >-
            Total number of unique email opens.
        spamReports:
          type: integer
          format: int64
          description: >-
            Total number of spam reports.
        blocked:
          type: integer
          format: int64
          description: >-
            Total number of blocked emails.
        invalid:
          type: integer
          format: int64
          description: >-
            Total number of invalid email addresses.
        unsubscribed:
          type: integer
          format: int64
          description: >-
            Total number of unsubscribes.
    TemplateList:
      type: object
      properties:
        count:
          type: integer
          format: int64
          description: >-
            Total number of templates available.
        templates:
          type: array
          description: >-
            List of email template summaries.
          items:
            $ref: '#/components/schemas/SmtpTemplate'
    SmtpTemplate:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: >-
            Unique identifier of the template.
        name:
          type: string
          description: >-
            Name of the template.
        subject:
          type: string
          description: >-
            Subject line of the template.
        isActive:
          type: boolean
          description: >-
            Whether the template is currently active.
        htmlContent:
          type: string
          description: >-
            HTML content of the template body.
        sender:
          type: object
          description: >-
            Default sender identity for the template.
          properties:
            name:
              type: string
              description: >-
                Sender display name.
            email:
              type: string
              format: email
              description: >-
                Sender email address.
        replyTo:
          type: string
          format: email
          description: >-
            Default reply-to email address for the template.
        createdAt:
          type: string
          format: date-time
          description: >-
            UTC date-time when the template was created.
        modifiedAt:
          type: string
          format: date-time
          description: >-
            UTC date-time when the template was last modified.
    CreateSmtpTemplate:
      type: object
      required:
        - templateName
        - sender
      properties:
        templateName:
          type: string
          description: >-
            Name for the new template.
        subject:
          type: string
          description: >-
            Default subject line for the template.
        htmlContent:
          type: string
          description: >-
            HTML content for the template body.
        sender:
          type: object
          description: >-
            Default sender identity for the template.
          required:
            - email
          properties:
            name:
              type: string
              description: >-
                Sender display name.
            email:
              type: string
              format: email
              description: >-
                Sender email address.
        replyTo:
          type: string
          format: email
          description: >-
            Default reply-to email address.
        isActive:
          type: boolean
          description: >-
            Whether to activate the template immediately.
    UpdateSmtpTemplate:
      type: object
      properties:
        templateName:
          type: string
          description: >-
            Updated name for the template.
        subject:
          type: string
          description: >-
            Updated subject line for the template.
        htmlContent:
          type: string
          description: >-
            Updated HTML content for the template body.
        sender:
          type: object
          description: >-
            Updated sender identity for the template.
          properties:
            name:
              type: string
              description: >-
                Sender display name.
            email:
              type: string
              format: email
              description: >-
                Sender email address.
        replyTo:
          type: string
          format: email
          description: >-
            Updated reply-to email address.
        isActive:
          type: boolean
          description: >-
            Whether the template should be active.
    CreateTemplateResponse:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: >-
            Unique identifier of the newly created template.
    TransactionalEmailContent:
      type: object
      properties:
        email:
          type: string
          format: email
          description: >-
            Recipient email address.
        subject:
          type: string
          description: >-
            Rendered subject line of the sent email.
        body:
          type: string
          description: >-
            Rendered HTML body of the sent email.
        date:
          type: string
          format: date-time
          description: >-
            UTC date-time when the email was sent.
        messageId:
          type: string
          description: >-
            Unique message identifier.
    SenderList:
      type: object
      properties:
        senders:
          type: array
          description: >-
            List of configured sender identities.
          items:
            type: object
            properties:
              id:
                type: integer
                format: int64
                description: >-
                  Unique identifier of the sender.
              name:
                type: string
                description: >-
                  Display name of the sender.
              email:
                type: string
                format: email
                description: >-
                  Email address of the sender.
              active:
                type: boolean
                description: >-
                  Whether the sender is verified and active.
    CreateSender:
      type: object
      required:
        - name
        - email
      properties:
        name:
          type: string
          description: >-
            Display name for the new sender.
        email:
          type: string
          format: email
          description: >-
            Email address for the new sender.
    CreateSenderResponse:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: >-
            Unique identifier of the newly created sender.
    ErrorResponse:
      type: object
      properties:
        code:
          type: string
          description: >-
            Error code identifying the type of error.
        message:
          type: string
          description: >-
            Human-readable description of the error.