openapi: 3.1.0
info:
  title: Brevo Contacts Agent Status Transactional Emails API
  description: The Brevo Contacts API provides programmatic access to contact management features including creating, updating, and deleting contacts. Developers can organize contacts into lists, apply attributes and tags, import contacts in bulk, and build audience segments for targeted campaigns. The API also supports managing folders, contact attributes, and custom fields to structure contact data according to business needs.
  version: '3.0'
  contact:
    name: Brevo Support
    url: https://help.brevo.com
  termsOfService: https://www.brevo.com/legal/termsofuse/
servers:
- url: https://api.brevo.com/v3
  description: Brevo Production API Server
security:
- apiKeyAuth: []
tags:
- name: Transactional Emails
  description: Send and manage transactional emails including order confirmations, password resets, and account notifications.
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/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'
components:
  schemas:
    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.
    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.
    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.
    SendEmailResponse:
      type: object
      properties:
        messageId:
          type: string
          description: Unique identifier assigned to the sent email message.
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: api-key
      description: Brevo API key passed in the api-key request header for authentication.
externalDocs:
  description: Brevo Contacts Documentation
  url: https://developers.brevo.com/docs/how-it-works