openapi: 3.1.0 info: title: Brevo Email Campaigns API description: >- The Brevo Email Campaigns API enables developers to create, manage, and send marketing email campaigns programmatically. It provides endpoints for building campaigns with HTML content or templates, scheduling sends, segmenting audiences, and managing sender identities. Developers can retrieve campaign statistics including open rates, click rates, and unsubscribes to measure performance and optimize future campaigns. version: '3.0' contact: name: Brevo Support url: https://help.brevo.com termsOfService: https://www.brevo.com/legal/termsofuse/ externalDocs: description: Brevo Email Campaigns Documentation url: https://developers.brevo.com/docs/getting-started servers: - url: https://api.brevo.com/v3 description: Brevo Production API Server tags: - name: Campaign Statistics description: >- Retrieve performance metrics and statistics for email campaigns. - name: Email Campaigns description: >- Create, update, send, and manage marketing email campaigns. security: - apiKeyAuth: [] 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' /emailCampaigns/{campaignId}/exportRecipients: post: operationId: exportCampaignRecipients summary: Export recipients of an email campaign description: >- Exports the recipients of a specific email campaign for analysis or processing. The exported data includes recipient details and their interaction status. tags: - Campaign Statistics parameters: - $ref: '#/components/parameters/campaignIdParam' requestBody: content: application/json: schema: type: object properties: notifyURL: type: string format: uri description: >- URL to receive a notification when the export is ready. recipientsType: type: string description: >- Type of recipients to export. enum: - all - nonClickers - nonOpeners - clickers - openers - softBounces - hardBounces - unsubscribed responses: '202': description: Export request accepted content: application/json: schema: type: object properties: processId: type: integer format: int64 description: >- Identifier for the export process. '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: 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 campaignIdParam: name: campaignId in: path required: true description: >- Unique identifier of the email campaign. schema: type: integer format: int64 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' 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. 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. 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 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.