Account-level administration: sender identities and IPs, sending domain creation and authentication, webhook subscriptions, organization users and permissions, master-account and sub-account management, background process status, and external RSS feeds.
openapi: 3.1.0
info:
title: Accounts and Settings
version: 1.0.0
paths:
/senders:
get:
operationId: getSenders
summary: Get email senders
description: |
Retrieves a list of all email senders from your Brevo account with optional filtering.
**Use this to:**
- Get all available senders for email campaign setup
- Find sender details including ID, name, and email address
- Filter senders by IP address for dedicated IP users
- Filter senders by domain for domain-specific configurations
- Monitor sender configuration and status
**Key information returned:**
- Sender details (ID, name, email address)
- Sender status and verification information
- Associated IP addresses and domains (for dedicated IP accounts)
- Sender configuration settings
**Important considerations:**
- Standard accounts show empty IP arrays, dedicated IP accounts show IP assignments
- Filtering by IP only available for accounts with dedicated IPs
- Domain filtering helps organize senders by business units or brands
- Sender status indicates if sender is active and ready for campaign use
- Email verification required before sender can be used in campaigns
tags:
- senders
parameters:
- name: ip
in: query
description: |
Filter your senders for a specific ip. **Available for dedicated IP usage only**
required: false
schema:
type: string
- name: domain
in: query
description: Filter your senders for a specific domain
required: false
schema:
type: string
- 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: List of senders retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Senders_getSenders_Response_200'
'400':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/GetSendersRequestBadRequestError'
post:
operationId: createSender
summary: Create email sender
description: |
Creates a new email sender in your Brevo account.
**Use this to:**
- Add new senders for email campaigns
- Configure sender identity (name and email)
- Associate dedicated IPs with the sender (for dedicated IP accounts)
- Set up domain-based sender configurations
**Key information returned:**
- Created sender ID
- DKIM and SPF configuration status
- Success confirmation
**Important considerations:**
- Verification email sent to specified sender address
- DKIM and SPF configuration affects deliverability
- Dedicated IP accounts require IP association during creation
- IP weights must sum to 100 when specified
- Sender must be verified before use in campaigns
tags:
- senders
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: Sender created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Senders_createSender_Response_201'
'400':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSenderRequestBadRequestError'
requestBody:
description: sender's configuration
content:
application/json:
schema:
type: object
properties:
email:
type: string
format: email
description: |-
From email to use for the sender. A verification email will be
sent to this address.
ips:
type: array
items:
$ref: '#/components/schemas/SendersPostRequestBodyContentApplicationJsonSchemaIpsItems'
description: |-
**Mandatory in case of dedicated IP**. IPs to associate to the
sender. Not required for standard accounts.
name:
type: string
description: From Name to use for the sender
required:
- email
- name
/senders/{senderId}:
put:
operationId: updateSender
summary: Update a sender
description: |-
Updates an existing email sender's configuration.
Use this to:
- Modify sender display name or email address
- Update dedicated IP associations
- Change sender configuration settings
- Correct sender information
Key information returned:
- Success confirmation
- Updated sender details
tags:
- senders
parameters:
- name: senderId
in: path
description: Id of the sender
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: Sender updated successfully
content:
application/json:
schema:
type: object
properties: {}
'400':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateSenderRequestBadRequestError'
'404':
description: Sender ID not found
content:
application/json:
schema:
$ref: '#/components/schemas/errorModel'
requestBody:
description: sender's configuration to update
content:
application/json:
schema:
type: object
properties:
email:
type: string
format: email
description: From Email to update the sender
ips:
type: array
items:
$ref: '#/components/schemas/SendersSenderIdPutRequestBodyContentApplicationJsonSchemaIpsItems'
description: |-
**Only in case of dedicated IP**. IPs to associate to the
sender. If passed, will replace all the existing IPs. Not required for standard accounts.
name:
type: string
description: From Name to update the sender
delete:
operationId: deleteSender
summary: Delete a sender
description: |-
Deletes an email sender from your Brevo account.
Use this to:
- Remove senders that are no longer needed
- Clean up sender configurations
- Remove duplicate or test senders
Key information returned:
- Success confirmation message
tags:
- senders
parameters:
- name: senderId
in: path
description: Id of the sender
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: Sender deleted successfully
content:
application/json:
schema:
type: object
properties: {}
'400':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteSenderRequestBadRequestError'
'404':
description: Sender ID not found
content:
application/json:
schema:
$ref: '#/components/schemas/errorModel'
/senders/{senderId}/validate:
put:
operationId: validateSenderByOTP
summary: Validate a sender using OTP
description: |-
Validates a sender using the OTP (One-Time Password) received via email.
Use this to:
- Complete sender verification process
- Activate a newly created sender
- Verify ownership of the sender email address
- Enable the sender for use in email campaigns
Key information returned:
- Success confirmation of sender verification
- Sender activation status
tags:
- senders
parameters:
- name: senderId
in: path
description: Id of the sender
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: Sender verified successfully
content:
application/json:
schema:
type: object
properties: {}
'400':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ValidateSenderByOTPRequestBadRequestError'
'404':
description: Sender ID not found
content:
application/json:
schema:
$ref: '#/components/schemas/errorModel'
requestBody:
description: OTP verification code
content:
application/json:
schema:
type: object
properties:
otp:
type: integer
description: 6 digit OTP received on email
required:
- otp
/senders/ips:
get:
operationId: getIps
summary: Get all the dedicated IPs for your account
description: |-
Retrieves all dedicated IPs associated with your Brevo account.
Use this to:
- List all your dedicated IPs
- Check the status of your dedicated IPs (active/inactive)
- Find IP addresses and associated domains for configuration purposes
- Monitor your IP reputation and deliverability
- Verify available IPs for sender configuration
Key information returned:
- IP ID and address
- Associated domain
- Active status
- IP configuration details
tags:
- senders
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:
'200':
description: List of dedicated IPs retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Senders_getIps_Response_200'
'400':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/GetIpsRequestBadRequestError'
/senders/{senderId}/ips:
get:
operationId: getIpsFromSender
summary: Get all the dedicated IPs for a specific sender
description: |-
Retrieves the dedicated IPs associated with a specific sender.
Use this to:
- Check IP configuration for a sender
- Verify dedicated IP associations
- Get IP details for troubleshooting
- Monitor sender IP configuration
Key information returned:
- List of associated dedicated IPs
- IP addresses and domain configurations
- IP status and settings
tags:
- senders
parameters:
- name: senderId
in: path
description: Id of the sender
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:
'200':
description: List of dedicated IPs retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Senders_getIpsFromSender_Response_200'
'400':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/GetIpsFromSenderRequestBadRequestError'
'404':
description: Sender ID not found
content:
application/json:
schema:
$ref: '#/components/schemas/errorModel'
/senders/domains:
get:
operationId: getDomains
summary: Get the list of all sender domains
description: |-
Retrieves all domains associated with the account.
Use this to:
- List all domains
- Verify domain existence
- Check domain authentication and verification status
- Monitor domain configuration and provider information
- Review domain creation history and ownership
Key information returned:
- Domain details (ID, name, authentication status)
- Verification and authentication states
- Associated IP addresses and DNS providers
- Creator information and creation timestamps
- Pagination information for large domain lists
tags:
- domains
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:
'200':
description: List of domains retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Domains_getDomains_Response_200'
'400':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/GetDomainsRequestBadRequestError'
post:
operationId: createDomain
summary: Create a new sender domain
description: |-
Creates a new domain in Brevo.
Use this to:
- Add new domains for sending emails
- Set up domain authentication for better deliverability
- Configure DNS records for email authentication
- Establish domain-based sender identities
Key information returned:
- Created domain ID and configuration
- Required DNS records for authentication
- Domain provider detection results
- Setup instructions and next steps
tags:
- domains
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:
'200':
description: Domain created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Domains_createDomain_Response_200'
'400':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDomainRequestBadRequestError'
requestBody:
description: Domain configuration
content:
application/json:
schema:
type: object
properties:
name:
type: string
format: hostname
description: Domain name to be added
required:
- name
/senders/domains/{domainName}:
delete:
operationId: deleteDomain
summary: Delete a sender domain
description: |-
Deletes a domain from Brevo.
Use this to:
- Remove existing domains
- Clean up unused domain configurations
- Remove test domains
Key information returned:
- Success confirmation message
tags:
- domains
parameters:
- name: domainName
in: path
description: Domain name
required: true
schema:
type: string
- 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: Domain deleted successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Domains_deleteDomain_Response_200'
'400':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteDomainRequestBadRequestError'
'404':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteDomainRequestNotFoundError'
get:
operationId: getDomainConfiguration
summary: Get a sender domain configuration
description: |-
Retrieves configuration of a specific domain, to know if the domain is valid or not.
Use this to:
- Check domain configuration
- Validate a domain configuration
- Monitor DNS record status
- Troubleshoot authentication issues
Key information returned:
- Domain verification and authentication status
- DNS records configuration and validation status
- Detailed authentication requirements
tags:
- domains
parameters:
- name: domainName
in: path
description: Domain name
required: true
schema:
type: string
- 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: Domain configuration retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Domains_getDomainConfiguration_Response_200'
'400':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/GetDomainConfigurationRequestBadRequestError'
'404':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/GetDomainConfigurationRequestNotFoundError'
/senders/domains/{domainName}/authenticate:
put:
operationId: authenticateDomain
summary: Authenticate a sender domain
description: |-
Authenticates a specific domain.
Use this to:
- Authenticate a domain
- Verify DNS record configuration
- Complete domain setup for sending
- Enable domain for email authentication
Key information returned:
- Authentication success confirmation
- Domain readiness status for email sending
tags:
- domains
parameters:
- name: domainName
in: path
description: Domain name
required: true
schema:
type: string
- 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: Domain authenticated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Domains_authenticateDomain_Response_200'
'400':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/AuthenticateDomainRequestBadRequestError'
'404':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/AuthenticateDomainRequestNotFoundError'
/webhooks:
get:
operationId: getWebhooks
summary: Get all webhooks
description: |-
Retrieves all webhooks from your Brevo account with filtering and sorting options.
Use this to:
- Monitor webhook configurations and event handling
- List webhooks by type (transactional, marketing, inbound)
- Review webhook endpoints and authentication
- Track webhook creation and modification history
- Audit webhook event subscriptions
Key information returned:
- Complete webhook details and configuration
- Event types and channel subscriptions
- Authentication and security settings
- Webhook URLs and custom headers
- Creation and modification timestamps
tags:
- webhooks
parameters:
- name: type
in: query
description: Filter on webhook type
required: false
schema:
$ref: '#/components/schemas/WebhooksGetParametersType'
default: transactional
- name: sort
in: query
description: Sort the results in the ascending/descending order of webhook creation
required: false
schema:
$ref: '#/components/schemas/WebhooksGetParametersSort'
default: desc
- 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: Webhooks informations
content:
application/json:
schema:
$ref: '#/components/schemas/Webhooks_getWebhooks_Response_200'
'400':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/GetWebhooksRequestBadRequestError'
post:
operationId: createWebhook
summary: Create a webhook
description: |-
Creates a new webhook to receive real-time notifications for specified events.
Use this to:
- Set up event notifications for transactional or marketing emails
- Configure webhook endpoints for campaign tracking
- Enable real-time monitoring of email delivery status
- Subscribe to contact list changes and updates
- Implement custom event handling and automation
Key information returned:
- Created webhook ID and configuration
- Success confirmation and setup details
tags:
- webhooks
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/Webhooks_createWebhook_Response_201'
'400':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/CreateWebhookRequestBadRequestError'
requestBody:
description: Values to create a webhook
content:
application/json:
schema:
type: object
properties:
auth:
$ref: '#/components/schemas/WebhooksPostRequestBodyContentApplicationJsonSchemaAuth'
description: Add authentication on webhook url
batched:
type: boolean
description: To send batched webhooks
channel:
$ref: '#/components/schemas/WebhooksPostRequestBodyContentApplicationJsonSchemaChannel'
default: email
description: Channel of the webhook
description:
type: string
description: Description of the webhook
domain:
type: string
description: |-
Inbound domain of webhook, required in case of event type
`inbound`
events:
type: array
items:
$ref: '#/components/schemas/WebhooksPostRequestBodyContentApplicationJsonSchemaEventsItems'
description: |-
Events triggering the webhook. Required for transactional and
marketing types, optional for inbound type (defaults to
`inboundEmailProcessed`). Possible values for **Transactional**
type webhook: `sent` OR `request`, `delivered`, `hardBounce`,
`softBounce`, `blocked`, `spam`, `invalid`, `deferred`, `click`,
`opened`, `uniqueOpened` and `unsubscribed`. Possible values for
**Marketing** type webhook: `spam`, `opened`, `click`,
`hardBounce`, `softBounce`, `unsubscribed`, `listAddition`,
`delivered`, `contactUpdated` & `contactDeleted`. Possible values
for **Inbound** type webhook: `inboundEmailProcessed`.
headers:
type: array
items:
$ref: '#/components/schemas/WebhooksPostRequestBodyContentApplicationJsonSchemaHeadersItems'
description: Custom headers to be send with webhooks
type:
$ref: '#/components/schemas/WebhooksPostRequestBodyContentApplicationJsonSchemaType'
default: transactional
description: Type of the webhook
url:
type: string
format: url
description: URL of the webhook
required:
- url
/webhooks/{webhookId}:
get:
operationId: getWebhook
summary: Get a webhook details
description: |-
Retrieves detailed information about a specific webhook configuration.
Use this to:
- Get complete webhook configuration and settings
- Check webhook event subscriptions and triggers
- Review authentication and security settings
- Verify webhook URL and custom headers
- Access webhook creation and modification history
Key information returned:
- Complete webhook details and configuration
- Event types and channel subscriptions
- Authentication credentials and methods
- Custom headers and request settings
- Webhook status and activity information
tags:
- webhooks
parameters:
- name: webhookId
in: path
description: Id of the webhook
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:
'200':
description: Webhook informations
content:
application/json:
schema:
$ref: '#/components/schemas/getWebhook'
'400':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/GetWebhookRequestBadRequestError'
'404':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/GetWebhookRequestNotFoundError'
put:
operationId: updateWebhook
summary: Update a webhook
description: |-
Updates an existing webhook configuration and event subscriptions.
Use this to:
- Modify webhook event subscriptions and triggers
- Update webhook URL and endpoint configuration
- Change authentication settings and credentials
- Adjust custom headers and request parameters
- Enable or disable specific webhook events
Key information returned:
- Success confirmation of webhook updates
tags:
- webhooks
parameters:
- name: webhookId
in: path
description: Id of the webhook
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: Webhook updated
content:
application/json:
schema:
type: object
properties: {}
'400':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateWebhookRequestBadRequestError'
'404':
description: bad request
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateWebhookRequestNotFoundError'
requestBody:
description: Values to update a webhook
content:
application/json:
schema:
type: object
properties:
auth:
$ref: '#/components/schemas/WebhooksWebhookIdPutRequestBodyContentApplicationJsonSchemaAuth'
description: Add authentication on webhook url
batched:
type: boolean
description: To send batched webhooks
description:
type: string
description: Description of the webhook
domain:
type: string
description: Inbound domain of webhook, used in case of event type `inbound`
events:
type: array
items:
$ref: '#/components/schemas/WebhooksWebhookIdPutRequestBodyContentApplicationJsonSchemaEventsItems'
description: |-
- Events triggering the webhook. Possible values for
**Transactional** type webhook: #### `sent` OR `request`,
`delivered`, `hardBounce`, `softBounce`, `blocked`, `spam`,
`invalid`, `deferred`, `click`, `opened`, `uniqueOpened` and
`unsubscribed` - Possible values for **Marketing** type webhook:
#### `spam`, `opened`, `click`, `hardBounce`, `softBounce`,
`unsubscribed`, `listAddition` & `delivered` - Possible values
# --- truncated at 32 KB (287 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/brevo/refs/heads/main/openapi/brevo-accounts-and-settings-openapi.yml