Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Marketing Campaigns Email Campaigns API
version: 1.0.0
servers:
- url: https://api.brevo.com/v3
description: https://api.brevo.com/v3
tags:
- name: emailCampaigns
paths:
/emailCampaigns:
get:
operationId: getEmailCampaigns
summary: Return all your created email campaigns
description: '<Note>The response payload for this endpoint has changed
You now need to specify which type of statistics you would like to retrieve. For more information visit [this page](https://developers.brevo.com/changelog/2023/2/7).</Note>'
tags:
- emailCampaigns
parameters:
- name: type
in: query
description: Filter on the type of the campaigns
required: false
schema:
$ref: '#/components/schemas/EmailCampaignsGetParametersType'
- name: status
in: query
description: Filter on the status of the campaign
required: false
schema:
$ref: '#/components/schemas/EmailCampaignsGetParametersStatus'
- name: statistics
in: query
description: 'Filter on the type of statistics required. Example: **globalStats** value will only fetch globalStats info of the campaign in the returned response. This option only returns data for events that occurred in the last 6 months. For older campaigns, it is advisable to use the **Get Campaign Report** endpoint.'
required: false
schema:
$ref: '#/components/schemas/EmailCampaignsGetParametersStatistics'
- name: startDate
in: query
description: '**Mandatory if endDate is used.** Starting (urlencoded) UTC date-time (YYYY-MM-DDTHH:mm:ss.SSSZ) to filter the sent email campaigns. **Prefer to pass your timezone in date-time format for accurate result.** Only available if `status` is not passed or is set to `sent`. The date range between `startDate` and `endDate` must not exceed 2 years. `startDate` must not be in the future.
'
required: false
schema:
type: string
- name: endDate
in: query
description: '**Mandatory if startDate is used.** Ending (urlencoded) UTC date-time (YYYY-MM-DDTHH:mm:ss.SSSZ) to filter the sent email campaigns. **Prefer to pass your timezone in date-time format for accurate result.** Only available if `status` is not passed or is set to `sent`. The date range between `startDate` and `endDate` must not exceed 2 years. `endDate` must not be in the future.
'
required: false
schema:
type: string
- name: limit
in: query
description: Number of documents per page
required: false
schema:
type: integer
format: int64
default: 50
- name: offset
in: query
description: Index of the first document in the page
required: false
schema:
type: integer
format: int64
default: 0
- name: sort
in: query
description: Sort the results in the ascending/descending order of record creation. Default order is **descending** if `sort` is not passed
required: false
schema:
$ref: '#/components/schemas/EmailCampaignsGetParametersSort'
default: desc
- name: excludeHtmlContent
in: query
description: Use this flag to exclude htmlContent from the response body. If set to **true**, the htmlContent field will be returned as an empty string in the response body.
required: false
schema:
type: boolean
- name: excludePdfAttachment
in: query
description: Use this flag to filter out campaigns that have a PDF attachment. If set to **true**, only campaigns without a PDF attachment (or with no attachment at all) will be returned.
required: false
schema:
type: boolean
- name: api-key
in: header
description: The API key should be passed in the request headers as `api-key` for authentication.
required: true
schema:
type: string
responses:
'200':
description: Email campaigns information
content:
application/json:
schema:
$ref: '#/components/schemas/Email_Campaigns_getEmailCampaigns_Response_200'
'400':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/GetEmailCampaignsRequestBadRequestError'
post:
operationId: createEmailCampaign
summary: Create an email campaign
description: 'Create a new email campaign. The campaign requires at minimum a name and sender details, and is created in draft status by default. You must provide email content via one of three mutually exclusive options: htmlContent (inline HTML), htmlUrl (remote URL), or templateId (existing template); additionally, A/B testing can be enabled by setting abTesting to true with subjectA and subjectB, but this is incompatible with sendAtBestTime.'
tags:
- emailCampaigns
parameters:
- name: api-key
in: header
description: The API key should be passed in the request headers as `api-key` for authentication.
required: true
schema:
type: string
responses:
'201':
description: successfully created
content:
application/json:
schema:
$ref: '#/components/schemas/Email_Campaigns_createEmailCampaign_Response_201'
'400':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/CreateEmailCampaignRequestBadRequestError'
'405':
description: Method not allowed. Returned when using sendAtBestTime or abTesting features without the required premium plan.
content:
application/json:
schema:
$ref: '#/components/schemas/errorModel'
requestBody:
description: Values to create a campaign
content:
application/json:
schema:
type: object
properties:
abTesting:
type: boolean
default: false
description: 'Status of A/B Test. abTesting = false means it is disabled & abTesting = true means it is enabled. **subjectA, subjectB, splitRule, winnerCriteria & winnerDelay** will be considered when abTesting is set to true. subjectA & subjectB are mandatory together & subject if passed is ignored. **Can be set to true only if sendAtBestTime is false**. You will be able to set up two subject lines for your campaign and send them to a random sample of your total recipients. Half of the test group will receive version A, and the other half will receive version B
'
attachmentUrl:
type: string
format: url
description: 'Absolute url of the attachment (no local file). Extension allowed: #### xlsx, xls, ods, docx, docm, doc, csv, pdf, txt, gif, jpg, jpeg, png, tif, tiff, rtf, bmp, cgm, css, shtml, html, htm, zip, xml, ppt, pptx, tar, ez, ics, mobi, msg, pub and eps
'
emailExpirationDate:
$ref: '#/components/schemas/EmailCampaignsPostRequestBodyContentApplicationJsonSchemaEmailExpirationDate'
description: To reduce your carbon footprint, set an expiration date for your email. If supported, it will be automatically deleted from the recipient’s inbox, saving storage space and energy. Learn more about setting an email expiration date. For reference , ``https://help.brevo.com/hc/en-us/articles/4413566705298-Create-an-email-campaign``
footer:
type: string
description: Footer of the email campaign
header:
type: string
description: Header of the email campaign
htmlContent:
type: string
description: '**Mandatory if htmlUrl and templateId are empty.** Body of the message (HTML). Must have more than 10 characters and be less than 1MB in size. Cannot be used together with `htmlUrl` or `templateId`.
'
htmlUrl:
type: string
format: url
description: '**Mandatory if htmlContent and templateId are empty.** URL to the message (HTML). Cannot be used together with `htmlContent` or `templateId`. For example: **https://html.domain.com**
'
increaseRate:
type: integer
format: int64
description: '**Mandatory if ipWarmupEnable is set to true**. Set a percentage increase rate for warming up your ip. We recommend you set the increase rate to 30% per day. If you want to send the same number of emails every day, set the daily increase value to 0%.
'
initialQuota:
type: integer
format: int64
description: '**Mandatory if ipWarmupEnable is set to true**. Set an initial quota greater than 1 for warming up your ip. We recommend you set a value of 3000.
'
inlineImageActivation:
type: boolean
default: false
description: 'Use true to embedded the images in your email. Final size of the email should be less than **4MB**. Campaigns with embedded images can _not be sent to more than 5000 contacts_
'
ipWarmupEnable:
type: boolean
default: false
description: '**Available for dedicated ip clients**. Set this to true if you wish to warm up your ip.
'
mirrorActive:
type: boolean
description: Use true to enable the mirror link
name:
type: string
description: Name of the campaign
params:
type: object
additionalProperties:
description: Any type
description: 'Pass the set of attributes to customize the type classic campaign. For example: **{"FNAME":"Joe", "LNAME":"Doe"}**. Only available if **type** is **classic**. It''s considered only if campaign is in _New Template Language format_. The New Template Language is dependent on the values of **subject, htmlContent/htmlUrl, sender.name & toField**
'
previewText:
type: string
description: Preview text or preheader of the email campaign
recipients:
$ref: '#/components/schemas/EmailCampaignsPostRequestBodyContentApplicationJsonSchemaRecipients'
description: Segment ids and List ids to include/exclude from campaign
replyTo:
type: string
format: email
description: Email on which the campaign recipients will be able to reply to
scheduledAt:
type: string
description: 'Sending UTC date-time (YYYY-MM-DDTHH:mm:ss.SSSZ). **Prefer to pass your timezone in date-time format for accurate result**. If sendAtBestTime is set to true, your campaign will be sent according to the date passed (ignoring the time part). For example: **2017-06-01T12:30:00+02:00**
'
sendAtBestTime:
type: boolean
default: false
description: Set this to true if you want to send your campaign at best time.
sender:
$ref: '#/components/schemas/EmailCampaignsPostRequestBodyContentApplicationJsonSchemaSender'
description: 'Sender details including id or email and name (optional). Only one of either Sender’s email or Sender’s ID shall be passed in one request at a time. Passing both `email` and `id` will result in an error. For example: **{"name":"xyz", "email":"example@abc.com"}** or **{"name":"xyz", "id":123}**
'
splitRule:
type: integer
format: int64
description: 'Add the size of your test groups. **Mandatory if abTesting = true & ''recipients'' is passed**. We''ll send version A and B to a random sample of recipients, and then the winning version to everyone else
'
subject:
type: string
description: 'Subject of the campaign. **Mandatory if abTesting is false**. Ignored if abTesting is true.
'
subjectA:
type: string
description: 'Subject A of the campaign. **Mandatory if abTesting = true**. subjectA & subjectB should have unique value
'
subjectB:
type: string
description: 'Subject B of the campaign. **Mandatory if abTesting = true**. subjectA & subjectB should have unique value
'
tag:
type: string
description: Tag of the campaign
templateId:
type: integer
format: int64
description: '**Mandatory if htmlContent and htmlUrl are empty.** Id of the transactional email template with status _active_. Used to copy only its content fetched from htmlContent/htmlUrl to an email campaign for RSS feature. Cannot be used together with `htmlContent` or `htmlUrl`.
'
toField:
type: string
description: 'To personalize the **To** Field. If you want to include the first name and last name of your recipient, add **{FNAME} {LNAME}**. These contact attributes must already exist in your Brevo account. If input parameter **params** used please use **{{contact.FNAME}} {{contact.LNAME}}** for personalization
'
unsubscriptionPageId:
type: string
description: 'Enter an unsubscription page id. The page id is a 24 digit alphanumeric id that can be found in the URL when editing the page. If not entered, then the default unsubscription page will be used.
'
updateFormId:
type: string
description: '**Mandatory if templateId is used containing the {{ update_profile }} tag**. Enter an update profile form id. The form id is a 24 digit alphanumeric id that can be found in the URL when editing the form. If not entered, then the default update profile form will be used.
'
utmCampaign:
type: string
description: Customize the utm_campaign value. If this field is empty, the campaign name will be used. Only alphanumeric characters and spaces are allowed
utmContent:
type: string
description: Customize the utm_content value. Appears on outgoing tracking links alongside utm_campaign. Only alphanumeric characters and spaces are allowed
utmTerm:
type: string
description: Customize the utm_term value. Appears on outgoing tracking links alongside utm_campaign. Only alphanumeric characters and spaces are allowed
winnerCriteria:
$ref: '#/components/schemas/EmailCampaignsPostRequestBodyContentApplicationJsonSchemaWinnerCriteria'
description: 'Choose the metrics that will determinate the winning version. **Mandatory if _splitRule_ >= 1 and < 50**. If splitRule = 50, `winnerCriteria` is ignored if passed
'
winnerDelay:
type: integer
format: int64
description: 'Choose the duration of the test in hours. Maximum is 7 days, pass 24*7 = 168 hours. The winning version will be sent at the end of the test. **Mandatory if _splitRule_ >= 1 and < 50**. If splitRule = 50, `winnerDelay` is ignored if passed
'
required:
- name
- sender
/emailCampaigns/{campaignId}:
put:
operationId: updateEmailCampaign
summary: Update an email campaign
description: Update an existing email campaign''s properties such as name, subject, content, sender, recipients, schedule, and A/B testing configuration. The campaign must exist and the request body must contain at least one valid field to update. Only draft or scheduled campaigns can be modified; if sendAtBestTime is enabled, IP warmup will be automatically disabled.
tags:
- emailCampaigns
parameters:
- name: campaignId
in: path
description: Id of the campaign
required: true
schema:
type: integer
format: int64
- name: api-key
in: header
description: The API key should be passed in the request headers as `api-key` for authentication.
required: true
schema:
type: string
responses:
'204':
description: Email campaign updated
content:
application/json:
schema:
type: object
properties: {}
'400':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateEmailCampaignRequestBadRequestError'
'404':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateEmailCampaignRequestNotFoundError'
'405':
description: Method not allowed. Returned when using sendAtBestTime or abTesting features without the required premium plan.
content:
application/json:
schema:
$ref: '#/components/schemas/errorModel'
requestBody:
description: Values to update a campaign
content:
application/json:
schema:
type: object
properties:
abTesting:
type: boolean
default: false
description: 'Status of A/B Test. abTesting = false means it is disabled & abTesting = true means it is enabled. **subjectA, subjectB, splitRule, winnerCriteria & winnerDelay** will be considered when abTesting is set to true. subjectA & subjectB are mandatory together & subject if passed is ignored. **Can be set to true only if sendAtBestTime is false**. You will be able to set up two subject lines for your campaign and send them to a random sample of your total recipients. Half of the test group will receive version A, and the other half will receive version B
'
attachmentUrl:
type: string
format: url
description: 'Absolute url of the attachment (no local file). Extension allowed: #### xlsx, xls, ods, docx, docm, doc, csv, pdf, txt, gif, jpg, jpeg, png, tif, tiff, rtf, bmp, cgm, css, shtml, html, htm, zip, xml, ppt, pptx, tar, ez, ics, mobi, msg, pub and eps''
'
emailExpirationDate:
$ref: '#/components/schemas/EmailCampaignsCampaignIdPutRequestBodyContentApplicationJsonSchemaEmailExpirationDate'
description: To reduce your carbon footprint, set an expiration date for your email. If supported, it will be automatically deleted from the recipient’s inbox, saving storage space and energy.
footer:
type: string
description: Footer of the email campaign
header:
type: string
description: Header of the email campaign
htmlContent:
type: string
description: 'Body of the message (HTML version). If the campaign is designed using Drag & Drop editor via HTML content, then the design page will not have Drag & Drop editor access for that campaign. **REQUIRED if htmlUrl is empty**
'
htmlUrl:
type: string
format: url
description: 'Url which contents the body of the email message. **REQUIRED if htmlContent is empty**
'
increaseRate:
type: integer
format: int64
description: 'Set a percentage increase rate for warming up your ip. We recommend you set the increase rate to 30% per day. If you want to send the same number of emails every day, set the daily increase value to 0%.
'
initialQuota:
type: integer
format: int64
description: 'Set an initial quota greater than 1 for warming up your ip. We recommend you set a value of 3000.
'
inlineImageActivation:
type: boolean
default: false
description: 'Status of inline image. inlineImageActivation = false means image can’t be embedded, & inlineImageActivation = true means image can be embedded, in the email. You cannot send a campaign of more than **4MB** with images embedded in the email. Campaigns with the images embedded in the email _must be sent to less than 5000 contacts_.
'
ipWarmupEnable:
type: boolean
default: false
description: '**Available for dedicated ip clients**. Set this to true if you wish to warm up your ip.
'
mirrorActive:
type: boolean
description: Status of mirror links in campaign. mirrorActive = false means mirror links are deactivated, & mirrorActive = true means mirror links are activated, in the campaign
name:
type: string
description: Name of the campaign
params:
type: object
additionalProperties:
description: Any type
description: 'Pass the set of attributes to customize the type classic campaign. For example: **{"FNAME":"Joe", "LNAME":"Doe"}**. Only available if **type** is **classic**. It''s considered only if campaign is in _New Template Language format_. The New Template Language is dependent on the values of **subject, htmlContent/htmlUrl, sender.name & toField**
'
previewText:
type: string
description: Preview text or preheader of the email campaign
recipients:
$ref: '#/components/schemas/EmailCampaignsCampaignIdPutRequestBodyContentApplicationJsonSchemaRecipients'
description: Segment ids and List ids to include/exclude from campaign
recurring:
type: boolean
default: false
description: '**FOR TRIGGER ONLY !** Type of trigger campaign.recurring = false means contact can receive the same Trigger campaign only once, & recurring = true means contact can receive the same Trigger campaign several times
'
replyTo:
type: string
format: email
description: Email on which campaign recipients will be able to reply to
scheduledAt:
type: string
description: 'UTC date-time on which the campaign has to run (YYYY-MM-DDTHH:mm:ss.SSSZ). **Prefer to pass your timezone in date-time format for accurate result.** If sendAtBestTime is set to true, your campaign will be sent according to the date passed (ignoring the time part).
'
sendAtBestTime:
type: boolean
description: 'Set this to true if you want to send your campaign at best time. Note:- **if true, warmup ip will be disabled.**
'
sender:
$ref: '#/components/schemas/EmailCampaignsCampaignIdPutRequestBodyContentApplicationJsonSchemaSender'
description: 'Sender details including id or email and name (optional). Only one of either Sender''s email or Sender''s ID shall be passed in one request at a time. For example: **{"name":"xyz", "email":"example@abc.com"}** **{"name":"xyz", "id":123}**
'
splitRule:
type: integer
format: int64
description: 'Add the size of your test groups. **Mandatory if abTesting = true & ''recipients'' is passed**. We''ll send version A and B to a random sample of recipients, and then the winning version to everyone else
'
subject:
type: string
description: Subject of the campaign
subjectA:
type: string
description: 'Subject A of the campaign. **Mandatory if abTesting = true**. subjectA & subjectB should have unique value
'
subjectB:
type: string
description: 'Subject B of the campaign. **Mandatory if abTesting = true**. subjectA & subjectB should have unique value
'
tag:
type: string
description: Tag of the campaign
toField:
type: string
description: 'To personalize the **To** Field. If you want to include the first name and last name of your recipient, add **{FNAME} {LNAME}**. These contact attributes must already exist in your Brevo account. If input parameter **params** used please use **{{contact.FNAME}} {{contact.LNAME}}** for personalization
'
unsubscriptionPageId:
type: string
description: 'Enter an unsubscription page id. The page id is a 24 digit alphanumeric id that can be found in the URL when editing the page.
'
updateFormId:
type: string
description: '**Mandatory if templateId is used containing the {{ update_profile }} tag**. Enter an update profile form id. The form id is a 24 digit alphanumeric id that can be found in the URL when editing the form.
'
utmCampaign:
type: string
description: Customize the utm_campaign value. If this field is empty, the campaign name will be used. Only alphanumeric characters and spaces are allowed
utmContent:
type: string
description: Customize the utm_content value. Appears on outgoing tracking links alongside utm_campaign. Only alphanumeric characters and spaces are allowed
utmTerm:
type: string
description: Customize the utm_term value. Appears on outgoing tracking links alongside utm_campaign. Only alphanumeric characters and spaces are allowed
winnerCriteria:
$ref: '#/components/schemas/EmailCampaignsCampaignIdPutRequestBodyContentApplicationJsonSchemaWinnerCriteria'
description: 'Choose the metrics that will determinate the winning version. **Mandatory if _splitRule_ >= 1 and < 50**. If splitRule = 50, `winnerCriteria` is ignored if passed
'
winnerDelay:
type: integer
format: int64
description: 'Choose the duration of the test in hours. Maximum is 7 days, pass 24*7 = 168 hours. The winning version will be sent at the end of the test. **Mandatory if _splitRule_ >= 1 and < 50**. If splitRule = 50, `winnerDelay` is ignored if passed
'
delete:
operationId: deleteEmailCampaign
summary: Delete an email campaign
description: Delete an email campaign by its campaign ID. Only campaigns that have not been scheduled can be deleted; attempting to delete a campaign that has already been scheduled will return a 403 permission denied error. Related data in templates, newsletter builder, and schedule collections is also cleaned up.
tags:
- emailCampaigns
parameters:
- name: campaignId
in: path
description: id of the campaign
required: true
schema:
type: integer
format: int64
- name: api-key
in: header
description: The API key should be passed in the request headers as `api-key` for authentication.
required: true
schema:
type: string
responses:
'204':
description: Email campaign has been deleted
content:
application/json:
schema:
type: object
properties: {}
'400':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteEmailCampaignRequestBadRequestError'
'403':
description: Permission denied. A campaign that has already been scheduled cannot be deleted.
content:
application/json:
schema:
$ref: '#/components/schemas/errorModel'
'404':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteEmailCampaignRequestNotFoundError'
get:
operationId: getEmailCampaign
summary: Get an email campaign report
description: Retrieve detailed information about a specific email campaign by its ID, including recipients, statistics, and HTML content. Use the statistics query parameter to select which statistics to include (globalStats, linksStats, statsByDomain, statsByDevice, or statsByBrowser); statsByDevice and statsByBrowser are only available on this single-campaign endpoint. You can exclude HTML content from the response by setting excludeHtmlContent to true.
tags:
- emailCampaigns
parameters:
- name: campaignId
in: path
description: Id of the campaign
required: true
schema:
type: integer
format: int64
- name: statistics
in: query
description: 'Filter on the type of statistics required. Example: **globalStats** value will only fetch globalStats info of the campaign in the returned response. `statsByDevice` and `statsByBrowser` are only available when retrieving a single campaign (not in the list endpoint).'
required: false
schema:
$ref: '#/components/schemas/EmailCampaignsCampaignIdGetParametersStatistics'
- name: excludeHtmlContent
in: query
description: Use this flag to exclude htmlContent from the response body. If set to **true**, htmlContent field will be returned as empty string in the response body
required: false
schema:
type: boolean
- name: api-key
in: header
description: The API key should be passed in the request headers as `api-key` for authentication.
required: true
schema:
type: string
responses:
'200':
description: Email campaign information
content:
application/json:
schema:
$ref: '#/components/schemas/Email_Campaigns_getEmailCampaign_Response_200'
'400':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/GetEmailCampaignRequestBadRequestError'
'404':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/GetEmailCampaignRequestNotFoundError'
/emailCampaigns/{campaignId}/sendNow:
post:
operationId: sendEmailCampaignNow
summary: Send
# --- truncated at 32 KB (113 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/brevo/refs/heads/main/openapi/brevo-emailcampaigns-api-openapi.yml