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.
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.