Lists and list additions
Read available lists, add People, and optionally create missing contacts.
The APIs on this page require alpha access for your organization. App availability and API access are separate. Check access and permissions.
List Brevo lists
GET /v1/brevo-integration/lists
Lists the Brevo account's contact lists, with their ids and names, read from Brevo now. Send next_cursor as cursor for the next page.
Requires brevo:config:read. The connection also needs access to the relevant tables, objects, or workflows.
MCP action: list_brevo_lists. Its arguments use the names below, except fields marked REST only. An HTTP header is passed using its argument name in MCP.
Parameters
| Name | Send in | Required | Type or allowed values | Notes |
|---|---|---|---|---|
cursor |
query | No | string |
Response
| HTTP status | Result |
|---|---|
200 |
The requested result. Asynchronous work returns an operation to poll. |
Required fields are required within their containing object. Notes identify fields that apply only to a particular response alternative.
| Response field | Type | Required in object | Notes |
|---|---|---|---|
data |
array of object | Yes | |
data[].object |
"brevo_list" |
Yes | |
data[].id |
integer | Yes | |
data[].name |
string | Yes | |
pagination |
object | Yes | |
pagination.next_cursor |
string or null | Yes |
Errors
| HTTP status | Meaning |
|---|---|
400 |
One of: credential_in_url, invalid_parameter, unknown_parameter, invalid_request, invalid_cursor. |
401 |
One of: missing_credential, invalid_credential, credential_expired, credential_revoked. |
402 |
One of: payment_overdue. |
403 |
The current permissions, plan or policy do not allow this request. |
404 |
One of: not_found. |
409 |
The request conflicts with current resource state, authorization or an earlier request. Read the error code and current resource before retrying. |
410 |
The requested resource or retained recovery data has expired. |
412 |
One of: version_conflict. |
413 |
One of: request_too_large. |
422 |
A field, filter or selection cannot be used for this request. |
423 |
One of: organization_reopening. |
428 |
One of: customer_agreement_required. |
429 |
One of: rate_limited. |
503 |
One of: service_unavailable. |
See errors and recovery and safe retries before repeating a write.
Add People to a Brevo list
POST /v1/brevo-integration/list-additions
Adds People to a Brevo list, including a list that starts a Brevo automation. By default only People who already exist in Brevo are added. You can also create a contact, with your saved attribute mappings, for anyone who doesn't have one. Nobody is resubscribed. An unsubscribed or blocked email address is skipped, and the Person's next email address is used instead; a Person whose identity needs review in Neon Deer is skipped. Through an AI app, the person who connected it is asked to accept the add first. The add runs in the background; follow the operation for each Person's result. Each Person's outcome names the last two addresses tried, ending with the one used, by where they came from (the profile contact, or its position among the Person's email addresses), never the address itself.
Requires brevo:execute. The connection also needs access to the relevant tables, objects, or workflows.
MCP action: create_brevo_list_additions. Its arguments use the names below, except fields marked REST only. An HTTP header is passed using its argument name in MCP.
Parameters
| Name | Send in | Required | Type or allowed values | Notes |
|---|---|---|---|---|
list_id |
JSON body | Yes | integer | |
record_ids |
JSON body | Yes | array of string (uuid) | |
create_missing |
JSON body | No | boolean | |
request_key |
Header: Idempotency-Key |
Yes | string |
Response
| HTTP status | Result |
|---|---|
202 |
The requested result. Asynchronous work returns an operation to poll. |
Required fields are required within their containing object. Notes identify fields that apply only to a particular response alternative.
| Response field | Type | Required in object | Notes |
|---|---|---|---|
data |
object | Yes | |
data.id |
string | Yes | |
data.object |
"operation" |
Yes | |
data.version |
string | Yes | |
data.resource_id |
string | Yes | |
data.resource_type |
string | Yes | |
data.status |
"pending", "succeeded", "failed", "canceled", "needs_attention" |
Yes | |
data.terminal |
boolean | Yes | |
data.created_at |
string (date-time) | Yes | |
data.ended_at |
string (date-time) or null | Yes | |
data.reason_code |
string or null | Yes | |
data.replayed |
true |
No | |
data.operation_type |
"scan_cancel", "ai_assessment", "ai_assessment_cancel", "review_update", "exclusion_create", "exclusion_update", "scheduled_batch_create", "scheduled_batch_update", "scheduled_batch_cancel", "scheduled_run_cancel", "scheduled_record_cancel", "schedule_create", "schedule_update", "webhook_endpoint_create", "webhook_endpoint_update", "webhook_secret_rotate", "endpoint_verification", "webhook_replay", "task_create", "task_update", "task_archive", "task_comment_create", "merge_rebuild", "scheduled_batch_transfer", "webhook_endpoint_transfer", "task_import" |
Yes | When data.operation_type is "scan_cancel", "ai_assessment", "ai_assessment_cancel", "review_update", "exclusion_create", "exclusion_update", "scheduled_batch_create", "scheduled_batch_update", "scheduled_batch_cancel", "scheduled_run_cancel", "scheduled_record_cancel", "schedule_create", "schedule_update", "webhook_endpoint_create", "webhook_endpoint_update", "webhook_secret_rotate", "endpoint_verification", "webhook_replay", "task_create", "task_update", "task_archive", "task_comment_create", "merge_rebuild", "scheduled_batch_transfer", "webhook_endpoint_transfer", "task_import". |
data.action_metadata |
object | Yes | |
data.action_metadata.resource_version |
string | Yes | |
data.action_metadata.allowed_actions |
array of string | Yes | |
data.operation_type |
"merge_execute", "merge_cancel" |
Yes | When data.operation_type is "merge_execute", "merge_cancel". |
data.action_metadata.execute_not_before |
string (date-time) | Yes | When data.operation_type is "merge_execute", "merge_cancel". |
data.action_metadata.authorization_expires_at |
string (date-time) | Yes | When data.operation_type is "merge_execute", "merge_cancel". |
data.operation_type |
"plan_prepare", "plan_revision_prepare", "retry_plan_prepare" |
Yes | When data.operation_type is "plan_prepare", "plan_revision_prepare", "retry_plan_prepare". |
data.action_metadata.plan_revision |
string | Yes | When data.operation_type is "plan_prepare", "plan_revision_prepare", "retry_plan_prepare". |
data.action_metadata.effects_digest |
string or null | Yes | When data.operation_type is "plan_prepare", "plan_revision_prepare", "retry_plan_prepare". |
data.action_metadata.preview_digest |
string or null | Yes | When data.operation_type is "plan_prepare", "plan_revision_prepare", "retry_plan_prepare". |
data.action_metadata.recovery_coverage_digest |
string or null | Yes | When data.operation_type is "plan_prepare", "plan_revision_prepare", "retry_plan_prepare". |
data.action_metadata.authorization_requirement |
object | Yes | When data.operation_type is "plan_prepare", "plan_revision_prepare", "retry_plan_prepare". |
data.action_metadata.authorization_requirement.scope |
"organization_baseline" |
Yes | When data.operation_type is "plan_prepare", "plan_revision_prepare", "retry_plan_prepare". |
data.action_metadata.authorization_requirement.mode |
"api_key_allowed", "not_allowed" |
Yes | When data.operation_type is "plan_prepare", "plan_revision_prepare", "retry_plan_prepare". |
data.action_metadata.authorization_requirement.policy_version |
string | Yes | When data.operation_type is "plan_prepare", "plan_revision_prepare", "retry_plan_prepare". |
data.action_metadata.authorization_requirement.grant_evaluation |
"at_execution" |
Yes | When data.operation_type is "plan_prepare", "plan_revision_prepare", "retry_plan_prepare". |
data.action_metadata.authorization_requirement.reason_code |
string or null | Yes | When data.operation_type is "plan_prepare", "plan_revision_prepare", "retry_plan_prepare". |
data.action_metadata.authorization_state |
"unauthorized", "authorized", "rejected", "invalidated", "expired" |
Yes | When data.operation_type is "plan_prepare", "plan_revision_prepare", "retry_plan_prepare". |
data.operation_type |
"review_bulk_update", "exclusion_bulk_create" |
Yes | When data.operation_type is "review_bulk_update", "exclusion_bulk_create". |
data.action_metadata.results |
array of object | Yes | When data.operation_type is "review_bulk_update", "exclusion_bulk_create". |
data.action_metadata.results[].index |
integer | Yes | When data.operation_type is "review_bulk_update", "exclusion_bulk_create". |
data.action_metadata.results[].outcome |
"succeeded", "failed" |
Yes | When data.operation_type is "review_bulk_update", "exclusion_bulk_create". |
data.action_metadata.results[].resource_ref |
object | No | When data.operation_type is "review_bulk_update", "exclusion_bulk_create". |
data.action_metadata.results[].resource_ref.id |
string | Yes | When data.operation_type is "review_bulk_update", "exclusion_bulk_create". |
data.action_metadata.results[].resource_ref.version |
string | Yes | When data.operation_type is "review_bulk_update", "exclusion_bulk_create". |
data.action_metadata.results[].error |
object | No | When data.operation_type is "review_bulk_update", "exclusion_bulk_create". |
data.action_metadata.results[].error.code |
string | Yes | When data.operation_type is "review_bulk_update", "exclusion_bulk_create". |
data.action_metadata.results[].error.message |
string | Yes | When data.operation_type is "review_bulk_update", "exclusion_bulk_create". |
data.action_metadata.results[].error.param |
string | No | When data.operation_type is "review_bulk_update", "exclusion_bulk_create". |
data.operation_type |
"scan", "scan_continue" |
Yes | When data.operation_type is "scan", "scan_continue". |
data.action_metadata.ai_child |
object | Yes | When data.operation_type is "scan", "scan_continue". |
data.action_metadata.ai_child.state |
"not_requested", "pending_admission", "admitted", "skipped", "failed" |
Yes | When data.operation_type is "scan", "scan_continue". |
data.action_metadata.ai_child.reason_code |
string or null | Yes | When data.operation_type is "scan", "scan_continue". |
data.action_metadata.ai_child.ai_run_id |
string | No | When data.operation_type is "scan", "scan_continue". |
data.action_metadata.ai_child.ai_operation_id |
string | No | When data.operation_type is "scan", "scan_continue". |
data.action_metadata.ai_child.operation_url |
string (uri) | No | When data.operation_type is "scan", "scan_continue". |
data.operation_type |
"brevo_list_add" |
Yes | When data.operation_type is "brevo_list_add". |
data.action_metadata.list_id |
integer | Yes | When data.operation_type is "brevo_list_add". |
data.action_metadata.records |
array of object | Yes | When data.operation_type is "brevo_list_add". When data.operation_type is "brevo_email_send". When data.operation_type is value. When data.operation_type is value. When data.operation_type is value. |
data.action_metadata.records[].record_id |
string | Yes | When data.operation_type is "brevo_list_add". When data.operation_type is "brevo_email_send". When data.operation_type is value. When data.operation_type is value. When data.operation_type is value. |
data.action_metadata.records[].outcome |
"pending", "added", "skipped", "unconfirmed", "failed" |
Yes | When data.operation_type is "brevo_list_add". When data.operation_type is value. |
data.action_metadata.records[].reason |
"restricted", "identity_hold", "monitoring_not_current", "no_email", "no_contact", "excluded", "changed", "confirming", "record_not_found" or null |
Yes | When data.operation_type is "brevo_list_add". |
data.action_metadata.records[].addresses |
array of object | Yes | When data.operation_type is "brevo_list_add". When data.operation_type is "brevo_email_send". |
data.action_metadata.records[].addresses[].source |
"profile" or object |
Yes | When data.operation_type is "brevo_list_add". When data.operation_type is "brevo_email_send". |
data.action_metadata.records[].addresses[].source.attribute |
"email_addresses" |
Yes | When data.operation_type is "brevo_list_add". When data.operation_type is "brevo_email_send". Alternative 2. |
data.action_metadata.records[].addresses[].source.position |
integer | Yes | When data.operation_type is "brevo_list_add". When data.operation_type is "brevo_email_send". Alternative 2. |
data.action_metadata.records[].addresses[].outcome |
"used", "skipped" |
Yes | When data.operation_type is "brevo_list_add". When data.operation_type is "brevo_email_send". |
data.action_metadata.records[].addresses[].reason |
"restricted" or null |
Yes | When data.operation_type is "brevo_list_add". When data.operation_type is "brevo_email_send". |
data.operation_type |
"brevo_email_send" |
Yes | When data.operation_type is "brevo_email_send". |
data.action_metadata.template_id |
integer | Yes | When data.operation_type is "brevo_email_send". |
data.action_metadata.records[].outcome |
"pending", "sent", "skipped", "unconfirmed", "failed" |
Yes | When data.operation_type is "brevo_email_send". When data.operation_type is value. |
data.action_metadata.records[].reason |
"restricted", "identity_hold", "monitoring_not_current", "no_email", "excluded", "recently_sent", "changed", "confirming", "record_not_found" or null |
Yes | When data.operation_type is "brevo_email_send". |
data.operation_type |
value | Yes | When data.operation_type is value. When data.operation_type is value. When data.operation_type is value. When data.operation_type is value. |
data.action_metadata.list_id |
string | Yes | When data.operation_type is value. When data.operation_type is value. |
data.action_metadata.records[].reason |
"restricted", "identity_hold", "monitoring_not_current", "no_contact", "excluded", "changed", "record_not_found" or null |
Yes | When data.operation_type is value. |
data.action_metadata.records[].outcome |
"pending", "removed", "skipped", "unconfirmed", "failed" |
Yes | When data.operation_type is value. |
data.action_metadata.records[].reason |
"not_in_list", "identity_hold", "no_contact", "changed", "record_not_found" or null |
Yes | When data.operation_type is value. |
data.action_metadata.outcome |
"pending", "unsubscribed", "unconfirmed", "failed", "skipped" |
Yes | When data.operation_type is value. |
data.action_metadata.reason |
"no_contact", "changed" or null |
Yes | When data.operation_type is value. |
data.action_metadata.metric |
string | Yes | When data.operation_type is value. |
data.action_metadata.properties |
object | Yes | When data.operation_type is value. |
data.action_metadata.properties.{key} |
string or number or boolean or null | No | When data.operation_type is value. Value for each key in this object. |
data.action_metadata.records[].reason |
"restricted", "identity_hold", "monitoring_not_current", "no_contact", "excluded", "recently_sent", "changed", "record_not_found" or null |
Yes | When data.operation_type is value. |
Accepted work can continue after the request returns. Follow its returned status or operation until it finishes; accepting work does not mean every item succeeded. See operation status.
Errors
| HTTP status | Meaning |
|---|---|
400 |
One of: credential_in_url, invalid_parameter, unknown_parameter, invalid_request. |
401 |
One of: missing_credential, invalid_credential, credential_expired, credential_revoked. |
402 |
One of: payment_overdue. |
403 |
The current permissions, plan or policy do not allow this request. |
404 |
One of: not_found. |
409 |
The request conflicts with current resource state, authorization or an earlier request. Read the error code and current resource before retrying. |
410 |
The requested resource or retained recovery data has expired. |
412 |
One of: version_conflict. |
413 |
One of: request_too_large. |
422 |
A field, filter or selection cannot be used for this request. |
423 |
One of: organization_reopening. |
428 |
One of: customer_agreement_required. |
429 |
One of: rate_limited. |
503 |
One of: service_unavailable. |
See errors and recovery and safe retries before repeating a write.
The public OpenAPI document lists generally available API families. Alpha operations may not appear in that document; their request and response fields are listed on this page. Use the API Playground to inspect a real response with your connection's access.