A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Brevo API is how an app or AI agent works with a Brevo account: managing contacts and lists, sending a transactional email, running an email or SMS campaign, and reading delivery and engagement reports. Access is granted through an account-level API key sent in a header, and that key carries full access with no granular scopes, so every read and write across the account runs under the same credential. Brevo can also push transactional and marketing events to a registered URL when something happens, like an email being delivered or a contact being added to a list.
How an app or AI agent connects to Brevo determines what it can reach. There is a route for making calls, a route for receiving events, and a hosted server that exposes Brevo tools to agents, and each is governed by the key behind it.
The REST API answers at https://api.brevo.com/v3. It takes JSON request bodies, returns JSON, and pages through lists with limit and offset query parameters. A call authenticates with an account API key sent in the api-key header.
Brevo POSTs a JSON payload to a registered URL when an event fires. There are two webhook types: transactional, for per-message email and SMS events like delivered, opened, and hard_bounce, and marketing, for events like list_addition, contact_updated, and unsubscribe.
Brevo publishes a first-party hosted Model Context Protocol server at https://mcp.brevo.com/v1/brevo/mcp that exposes Brevo tools to AI agents, with all features combined across modules and individual per-domain servers for areas like contacts, campaigns, and SMS. It authenticates with a Bearer token generated as an MCP API key in the account's API keys settings.
Brevo authenticates each request with an account-level API key sent in the api-key header. The key carries full access to every endpoint the account's plan allows, with no granular per-resource scopes, so any holder of the key can read and write across the whole account. Read-only versus write access and which areas an agent may touch have to be enforced outside Brevo.
The Brevo MCP server uses a dedicated MCP API key, generated in the account's API keys settings and sent as a Bearer token in the Authorization header. It grants the agent access through the MCP server rather than through direct REST calls.
The Brevo API is split into areas an agent can act on, like contacts, lists, transactional email, email campaigns, SMS, templates, and senders. Each area has its own methods, and writes in some areas send real messages to real people.
Create, read, update, and delete contacts, list every contact, and import contacts in bulk.
List and create contact lists, read the contacts in a list, and add or remove contacts from a list.
List the folders that organize contact lists and create a new folder.
Send a transactional email, read the per-message event report, and fetch a sent email's content.
List and create email campaigns, read a campaign's report, and send a campaign immediately.
Send a transactional SMS to a mobile number and send an SMS campaign to its audience.
List the transactional email templates and create a new one.
List senders, list and create webhooks, and read the account's plan and credit balance.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
ContactsCreate, read, update, and delete contacts, list every contact, and import contacts in bulk.6 | ||||||
| POST | /v3/contacts | Create a contact, optionally adding it to lists and setting attributes. | write | — | Current | |
A Brevo API key carries full account access, so there is no per-endpoint scope. Adding the contact to a list can fire a list_addition marketing webhook. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook event list_additionRate limit10 requests per second, 36,000 per hour (General tier) SourceOfficial documentation ↗ | ||||||
| GET | /v3/contacts | Get all the contacts in the account. | read | — | Current | |
Read-only. Returns email addresses and attributes for every contact. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limit10 requests per second, 36,000 per hour (General tier) SourceOfficial documentation ↗ | ||||||
| GET | /v3/contacts/{identifier} | Get a single contact's details by email, ID, or phone identifier. | read | — | Current | |
Read-only. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limit10 requests per second, 36,000 per hour (General tier) SourceOfficial documentation ↗ | ||||||
| PUT | /v3/contacts/{identifier} | Update a contact's attributes, list membership, or opt-in status. | write | — | Current | |
Can fire a contact_updated marketing webhook. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook event contact_updatedRate limit10 requests per second, 36,000 per hour (General tier) SourceOfficial documentation ↗ | ||||||
| DELETE | /v3/contacts/{identifier} | Delete a contact permanently. | write | — | Current | |
Irreversible. Can fire a contact_deleted marketing webhook. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook event contact_deletedRate limit10 requests per second, 36,000 per hour (General tier) SourceOfficial documentation ↗ | ||||||
| POST | /v3/contacts/import | Import contacts in bulk from a file or inline list, optionally into chosen lists. | write | — | Current | |
A single call can create or update many contacts at once and add them to lists. Acts oncontact Permission (capability)None required VersionAvailable since the API’s base version Webhook event list_additionRate limit10 requests per second, 36,000 per hour (General tier) SourceOfficial documentation ↗ | ||||||
Contact listsList and create contact lists, read the contacts in a list, and add or remove contacts from a list.5 | ||||||
| GET | /v3/contacts/lists | Get all the contact lists in the account. | read | — | Current | |
Read-only. Acts onlist Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/contacts/lists | Create a contact list inside a folder. | write | — | Current | |
A list must be created inside an existing folder. Acts onlist Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/contacts/lists/{listId}/contacts | Get the contacts that belong to a list. | read | — | Current | |
Read-only. Acts onlist Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/contacts/lists/{listId}/contacts/add | Add existing contacts to a list. | write | — | Current | |
Can fire a list_addition marketing webhook for each contact added. Acts onlist Permission (capability)None required VersionAvailable since the API’s base version Webhook event list_additionRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/contacts/lists/{listId}/contacts/remove | Remove contacts from a list. | write | — | Current | |
Removes the contacts from the list without deleting the contacts themselves. Acts onlist Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
FoldersList the folders that organize contact lists and create a new folder.2 | ||||||
| GET | /v3/contacts/folders | Get all the folders that organize contact lists. | read | — | Current | |
Read-only. Acts onfolder Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/contacts/folders | Create a folder to hold contact lists. | write | — | Current | |
A folder groups related contact lists. Acts onfolder Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Transactional emailSend a transactional email, read the per-message event report, and fetch a sent email's content.3 | ||||||
| POST | /v3/smtp/email | Send a transactional email to one or more recipients, from raw content or a template. | write | — | Current | |
Delivers a real email. Brevo emits delivery, open, click, and bounce events for it through transactional webhooks. Acts ontransactional email Permission (capability)None required VersionAvailable since the API’s base version Webhook event deliveredRate limit1,000 requests per second, 3,600,000 per hour (General tier) SourceOfficial documentation ↗ | ||||||
| GET | /v3/smtp/statistics/events | Get the per-message event report for transactional email activity. | read | — | Current | |
Read-only. Returns the event log of sent, delivered, opened, clicked, and bounced messages. Acts ontransactional email Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/smtp/emails/{uuid} | Get the content of a sent transactional email by its UUID. | read | — | Current | |
Read-only. Content is retained for a limited window after sending. Acts ontransactional email Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Email campaignsList and create email campaigns, read a campaign's report, and send a campaign immediately.3 | ||||||
| GET | /v3/emailCampaigns | Get all the email campaigns in the account. | read | — | Current | |
Read-only. Acts onemail campaign Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/emailCampaigns | Create an email campaign in draft, scheduled, or sent state. | write | — | Current | |
Creating a campaign does not send it unless it is set to send immediately. Acts onemail campaign Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/emailCampaigns/{campaignId}/sendNow | Send an email campaign immediately to its audience. | write | — | Current | |
Delivers to the whole campaign audience at once and cannot be recalled. Acts onemail campaign Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
SMSSend a transactional SMS to a mobile number and send an SMS campaign to its audience.2 | ||||||
| POST | /v3/transactionalSMS/send | Send a transactional SMS to a single mobile number. | write | — | Current | |
Delivers a real text message and consumes SMS credits. The older POST /v3/transactionalSMS/sms path is deprecated in favor of this one. Acts onSMS Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limit150 requests per second, 540,000 per hour (General tier) SourceOfficial documentation ↗ | ||||||
| POST | /v3/smsCampaigns/{campaignId}/sendNow | Send an SMS campaign immediately to its audience. | write | — | Current | |
Delivers to the whole campaign audience and consumes SMS credits per message. Acts onSMS campaign Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
TemplatesList the transactional email templates and create a new one.2 | ||||||
| GET | /v3/smtp/templates | Get all the transactional email templates. | read | — | Current | |
Read-only. Acts ontemplate Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/smtp/templates | Create a transactional email template. | write | — | Current | |
The template can then be referenced by transactional email sends. Acts ontemplate Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Senders, webhooks & accountList senders, list and create webhooks, and read the account's plan and credit balance.4 | ||||||
| GET | /v3/senders | Get the list of all senders configured in the account. | read | — | Current | |
Read-only. Acts onsender Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v3/webhooks | Create a webhook that posts chosen transactional or marketing events to a URL. | write | — | Current | |
Registers an event receiver. The webhook type, transactional or marketing, decides which events it can subscribe to. Acts onwebhook Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/webhooks | Get all the webhooks in the account. | read | — | Current | |
Read-only. Acts onwebhook Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v3/account | Get the account's information, plan, and remaining credits. | read | — | Current | |
Read-only. Reports the plan type and the email and SMS credit balance. Acts onaccount Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Brevo can notify an app when something happens, like a transactional email being delivered or opened, or a contact being added to a list. It posts a JSON payload to a registered URL, so an integration learns about activity without polling.
| Event | What it signals | Triggered by |
|---|---|---|
delivered | A transactional email was accepted and delivered to the recipient's mail server. | /v3/smtp/email |
opened | A delivered transactional email was opened by the recipient. Brevo also emits unique_opened for the first open. | /v3/smtp/email |
click | A link inside a delivered transactional email was clicked. | /v3/smtp/email |
hard_bounce | A transactional email permanently failed, for example because the address does not exist. | /v3/smtp/email |
list_addition | A contact was added to a list. Delivered through marketing webhooks. | /v3/contacts/v3/contacts/import/v3/contacts/lists/{listId}/contacts/add |
contact_updated | A contact's attributes or list membership changed. Delivered through marketing webhooks. | /v3/contacts/{identifier} |
contact_deleted | A contact was deleted. Delivered through marketing webhooks. | /v3/contacts/{identifier} |
Brevo limits how fast an app can call each endpoint, measured as requests per second and per hour, with higher ceilings on Professional and Enterprise plans.
Brevo sets a separate limit on each endpoint, expressed as both requests per second and requests per hour, and where both apply both must be respected at once. Limits are tiered by plan: a General tier applies to all accounts, an Advanced tier to Professional and Enterprise plans, and an Extended tier to Enterprise. On the General tier, transactional email sending allows 1,000 requests per second and 3,600,000 per hour, transactional SMS allows 150 per second and 540,000 per hour, and contact endpoints allow 10 per second and 36,000 per hour. Higher tiers raise these ceilings. Going over returns HTTP 429, and every response carries the x-sib-ratelimit-limit, x-sib-ratelimit-remaining, and x-sib-ratelimit-reset headers that report the current state.
List endpoints page with the limit and offset query parameters, where offset is 0-based, so the second page of 50 results uses offset=50. The default and maximum value of limit are set per endpoint rather than by one global rule, so the exact ceiling is given on each endpoint's reference page.
Request and response bodies are JSON, and the Content-Type must be application/json. A bulk contact import accepts many contacts in a single call, and the per-endpoint limit caps how large each page of a list response can be.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | invalid_parameter / missing_parameter | The request was bad: a parameter is missing, out of range, or invalid, with code strings like missing_parameter, invalid_parameter, out_of_range, or duplicate_parameter. | Read the message field, fix the named parameter, and resend. |
| 401 | unauthorized | The API key is missing or invalid. | Send a valid key in the api-key header, and rotate the key if it is compromised. |
| 402 | not_enough_credits | The account lacks the credits or activation needed for the request, for example to send email or SMS. | Top up credits or complete account validation, then retry. |
| 403 | permission_denied | The account is not permitted to perform this request, for example while it is under validation. | Resolve the account restriction, such as account_under_validation, before retrying. |
| 404 | document_not_found | The requested object does not exist or is not visible to this account. | Verify the identifier and that the object belongs to this account. |
| 405 | method_not_allowed | The HTTP method is not allowed on this endpoint. | Use the method documented for the endpoint. |
| 406 | not_acceptable | The Content-Type is not acceptable; Brevo expects application/json. | Set the Content-Type header to application/json. |
| 429 | too_many_requests | The endpoint's per-second or per-hour rate limit was exceeded. | Back off and retry, reading the x-sib-ratelimit-remaining and x-sib-ratelimit-reset headers. |
Brevo runs a single, continuously updated version 3 of its API, the line that carried over from the Sendinblue era, and ships dated changes through release notes rather than minting new version numbers.
The API has run on version 3 since the Sendinblue era and stays a single continuously updated line. Brevo does not mint new version numbers; it ships dated changes through release notes and SDK releases. The base host is api.brevo.com/v3, and access uses the api-key header.
Brevo shipped next-major SDK versions with breaking changes (Node.js v6.0.0, PHP v5.0.0, Python v5.0.0) alongside a rework of the OpenAPI spec to match real API behavior.
New endpoints and fields, including a paginated list of custom events, shipped in Node.js v5.0.3, PHP v4.0.11, and Python v4.0.9.
The Brevo MCP server's tools are now auto-generated from the OpenAPI spec, with improved security and rate limiting.
There is one current version; track the release notes for dated changes.
Brevo API changelog ↗Bollard AI sits between a team's AI agents and Brevo. Grant each agent exactly the access it needs, read or write, area by area, and every call is checked and logged.