brevo Email Campaigns API

openapi: 3.1.0
info:
  title: Brevo Contacts Agent Status Email Campaigns 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: Email Campaigns
  description: Create, update, send, and manage marketing email campaigns.
paths:
  /emailCampaigns:
    get:
      operationId: listEmailCampaigns
      summary: Return all email campaigns
      description: Retrieves a paginated list of all email campaigns created in the account. Supports filtering by type, status, and date range. Campaign statistics may be included in the response depending on the requested statistics type.
      tags:
      - Email Campaigns
      parameters:
      - $ref: '#/components/parameters/limitParam'
      - $ref: '#/components/parameters/offsetParam'
      - name: type
        in: query
        description: Filter by campaign type such as classic or trigger.
        schema:
          type: string
          enum:
          - classic
          - trigger
      - name: status
        in: query
        description: Filter by campaign status.
        schema:
          type: string
          enum:
          - draft
          - sent
          - archive
          - queued
          - suspended
          - in_process
      - name: startDate
        in: query
        description: Filter campaigns created on or after this date in YYYY-MM-DD format.
        schema:
          type: string
          format: date
      - name: endDate
        in: query
        description: Filter campaigns created on or before this date in YYYY-MM-DD format.
        schema:
          type: string
          format: date
      - name: statistics
        in: query
        description: Type of statistics to include in the response, such as globalStats or linksStats.
        schema:
          type: string
          enum:
          - globalStats
          - linksStats
      responses:
        '200':
          description: Email campaigns retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailCampaignList'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      operationId: createEmailCampaign
      summary: Create an email campaign
      description: Creates a new email campaign with the specified content, recipients, and scheduling options. The campaign can use HTML content or a pre-built template and can target specific lists or segments.
      tags:
      - Email Campaigns
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEmailCampaign'
      responses:
        '201':
          description: Email campaign created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    format: int64
                    description: Unique identifier of the newly created campaign.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /emailCampaigns/{campaignId}:
    get:
      operationId: getEmailCampaign
      summary: Get an email campaign
      description: Retrieves the details of a specific email campaign including its content, recipients, scheduling, and performance statistics.
      tags:
      - Email Campaigns
      parameters:
      - $ref: '#/components/parameters/campaignIdParam'
      - name: statistics
        in: query
        description: Type of statistics to include such as globalStats or linksStats.
        schema:
          type: string
          enum:
          - globalStats
          - linksStats
      responses:
        '200':
          description: Email campaign retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailCampaign'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Campaign not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      operationId: updateEmailCampaign
      summary: Update an email campaign
      description: Updates an existing email campaign with new content, recipients, or scheduling options. Only draft campaigns can be fully updated.
      tags:
      - Email Campaigns
      parameters:
      - $ref: '#/components/parameters/campaignIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateEmailCampaign'
      responses:
        '204':
          description: Campaign 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: Campaign not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      operationId: deleteEmailCampaign
      summary: Delete an email campaign
      description: Permanently deletes an email campaign by its unique identifier.
      tags:
      - Email Campaigns
      parameters:
      - $ref: '#/components/parameters/campaignIdParam'
      responses:
        '204':
          description: Campaign deleted successfully
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Campaign not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /emailCampaigns/{campaignId}/sendNow:
    post:
      operationId: sendEmailCampaignNow
      summary: Send an email campaign immediately
      description: Triggers the immediate sending of an email campaign that is in draft status. The campaign must have valid content and recipients configured before sending.
      tags:
      - Email Campaigns
      parameters:
      - $ref: '#/components/parameters/campaignIdParam'
      responses:
        '204':
          description: Campaign send triggered 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: Campaign not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /emailCampaigns/{campaignId}/sendTest:
    post:
      operationId: sendTestEmail
      summary: Send a test email for a campaign
      description: Sends a test version of an email campaign to the specified email addresses for review before launching the actual campaign.
      tags:
      - Email Campaigns
      parameters:
      - $ref: '#/components/parameters/campaignIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - emailTo
              properties:
                emailTo:
                  type: array
                  description: List of email addresses to send the test to.
                  items:
                    type: string
                    format: email
                  maxItems: 9
      responses:
        '204':
          description: Test email sent 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: Campaign not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    EmailCampaignList:
      type: object
      properties:
        count:
          type: integer
          format: int64
          description: Total number of email campaigns matching the filter criteria.
        campaigns:
          type: array
          description: List of email campaign summaries.
          items:
            $ref: '#/components/schemas/EmailCampaign'
    UpdateEmailCampaign:
      type: object
      properties:
        name:
          type: string
          description: Updated name for the campaign.
        subject:
          type: string
          description: Updated subject line.
        sender:
          type: object
          description: Updated sender identity.
          properties:
            name:
              type: string
              description: Sender display name.
            email:
              type: string
              format: email
              description: Sender email address.
        htmlContent:
          type: string
          description: Updated HTML content for the campaign body.
        scheduledAt:
          type: string
          format: date-time
          description: Updated scheduled send date-time.
        recipients:
          type: object
          description: Updated target audience.
          properties:
            listIds:
              type: array
              description: IDs of contact lists to target.
              items:
                type: integer
                format: int64
            exclusionListIds:
              type: array
              description: IDs of contact lists to exclude.
              items:
                type: integer
                format: int64
    CreateEmailCampaign:
      type: object
      required:
      - name
      - sender
      properties:
        name:
          type: string
          description: Name for the campaign used for internal identification.
        subject:
          type: string
          description: Subject line for the campaign email.
        sender:
          type: object
          description: Sender identity for the campaign.
          required:
          - email
          properties:
            name:
              type: string
              description: Sender display name.
            email:
              type: string
              format: email
              description: Sender email address.
        htmlContent:
          type: string
          description: HTML content for the campaign body.
        templateId:
          type: integer
          format: int64
          description: ID of a template to use for the campaign content.
        scheduledAt:
          type: string
          format: date-time
          description: UTC date-time to schedule the campaign send.
        recipients:
          type: object
          description: Target audience for the campaign.
          properties:
            listIds:
              type: array
              description: IDs of contact lists to target.
              items:
                type: integer
                format: int64
            exclusionListIds:
              type: array
              description: IDs of contact lists to exclude.
              items:
                type: integer
                format: int64
        replyTo:
          type: string
          format: email
          description: Reply-to email address for the campaign.
        tag:
          type: string
          description: Tag for categorizing the campaign.
    EmailCampaign:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier of the campaign.
        name:
          type: string
          description: Name of the campaign.
        subject:
          type: string
          description: Subject line of the campaign email.
        type:
          type: string
          description: Type of the campaign.
          enum:
          - classic
          - trigger
        status:
          type: string
          description: Current status of the campaign.
          enum:
          - draft
          - sent
          - archive
          - queued
          - suspended
          - in_process
        scheduledAt:
          type: string
          format: date-time
          description: UTC date-time when the campaign is scheduled to send.
        sender:
          type: object
          description: Sender identity used for the campaign.
          properties:
            name:
              type: string
              description: Sender display name.
            email:
              type: string
              format: email
              description: Sender email address.
        recipients:
          type: object
          description: Target audience configuration for the campaign.
          properties:
            lists:
              type: array
              description: List IDs to target with the campaign.
              items:
                type: integer
                format: int64
            exclusionLists:
              type: array
              description: List IDs to exclude from the campaign.
              items:
                type: integer
                format: int64
        statistics:
          type: object
          description: Campaign performance statistics when requested.
          properties:
            globalStats:
              type: object
              description: Aggregated performance metrics.
              properties:
                uniqueClicks:
                  type: integer
                  format: int64
                  description: Number of unique link clicks.
                clickers:
                  type: integer
                  format: int64
                  description: Number of unique recipients who clicked.
                complaints:
                  type: integer
                  format: int64
                  description: Number of spam complaints.
                delivered:
                  type: integer
                  format: int64
                  description: Number of successfully delivered emails.
                sent:
                  type: integer
                  format: int64
                  description: Number of emails sent.
                softBounces:
                  type: integer
                  format: int64
                  description: Number of soft bounces.
                hardBounces:
                  type: integer
                  format: int64
                  description: Number of hard bounces.
                uniqueViews:
                  type: integer
                  format: int64
                  description: Number of unique email opens.
                unsubscriptions:
                  type: integer
                  format: int64
                  description: Number of unsubscribes.
        createdAt:
          type: string
          format: date-time
          description: UTC date-time when the campaign was created.
        modifiedAt:
          type: string
          format: date-time
          description: UTC date-time when the campaign was last modified.
    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.
  parameters:
    offsetParam:
      name: offset
      in: query
      description: Number of results to skip for pagination.
      schema:
        type: integer
        format: int64
        default: 0
    campaignIdParam:
      name: campaignId
      in: path
      required: true
      description: Unique identifier of the email campaign.
      schema:
        type: integer
        format: int64
    limitParam:
      name: limit
      in: query
      description: Maximum number of results to return per request.
      schema:
        type: integer
        format: int64
        default: 50
  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