# Brevo API

Source: https://neondeerdata.com/docs/api/brevo/

Configure Brevo sync, inspect contact activity and unsubscribes, and add existing contacts to lists.

## Access

The Brevo app is generally available. Its API family still requires alpha access, Paid or an active trial, and the connection's permissions. MCP is generally available, but does not bypass those checks. Follow the [Brevo setup guide](https://neondeerdata.com/docs/platform/brevo/) to connect the accounts.

## Contact mappings and sync

Use [contact mappings and synchronization](https://neondeerdata.com/docs/api/brevo/contacts/) to inspect settings, configure mapped attributes, start an update, and review its result. Automatic sync updates existing contacts. The latest Attio app also provides a Create or update Brevo contact workflow step. There is no standalone contact-create or direct contact-value write operation. List additions can create missing contacts when requested, as described below. Install the latest Brevo app from Neon Deer for the corresponding Attio actions.

Attribute discovery returns the Person object's own attributes by default. Related objects are listed separately under `related_objects`; use `object` to request one. `search` matches attribute names without case sensitivity. Request `include_options=true` when you need selectable options; option lists are otherwise omitted. Callers using the earlier combined attribute list must adjust to this response.

## Lists and confirmation

[List additions](https://neondeerdata.com/docs/api/brevo/lists/) use existing Brevo contacts by default. Send `create_missing: true` to create a missing contact with the saved mappings and add it to the selected list. The default is false; updating all contacts does not create missing contacts. Review skipped or unconfirmed records. The previous `permission_confirmed` field has been removed; omit it from requests. Sending it is refused as an unknown member. Missing lists are refused before work is accepted. Retrying an accepted request with its original request key returns the existing receipt.

List additions do not resubscribe people or clear blocks. The consent checkbox has been removed. Over MCP, the connected person must still accept the addition; the question names the Brevo list where available and says when missing contacts will be created.

## Send a template email

[List active transactional templates and send an email](https://neondeerdata.com/docs/api/brevo/templates/) with `template_id` and the selected Attio Person `record_ids`. Template sends require `brevo:execute`. Each email goes to the Person's profile email address, whether or not a Brevo contact exists. Sending the email does not itself create a contact.

```bash
curl -X POST 'https://api.neondeerdata.com/v1/brevo-integration/email-sends' \
  -H "Authorization: Bearer $NEON_DEER_API_KEY" \
  -H "Idempotency-Key: $NEON_DEER_REQUEST_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"template_id":123,"record_ids":["3f6c2a9e-8b1d-4c7a-9e2f-5a1b7c4d8e90"]}'

```

Replace the example template and record IDs with the selected resources. Reuse the same request key when retrying the same request; do not create a fresh send to resolve an uncertain result. Follow the returned `brevo_email_send` operation and inspect each record's outcome: `pending`, `sent`, `skipped`, `unconfirmed`, or `failed`.

Unsubscribed or blocked profile addresses are skipped without trying another address. Identity holds and unavailable unsubscribe monitoring can also stop a send. A recent matching send is skipped as `recently_sent`. An `unconfirmed` email is not automatically sent again: check Brevo before deciding whether another send is appropriate. A successful send request does not confirm inbox delivery or that someone read the email.

Over MCP, use `list_brevo_templates` and `create_brevo_email_sends`. The connected person must accept the send; a client that cannot ask is refused. Refresh the client's tool list after updating the connection.

## Location and country mappings

Attribute discovery lists each supported part of an Attio location separately, with `kind: "location"` and `location_part`. The mapping read returns `attio_location_part`; send that field when writing a location mapping. Supported parts are `line_1`, `line_2`, `line_3`, `line_4`, `locality`, `region`, `postcode`, `country_code`, `latitude`, and `longitude`. It is null for mappings that do not use a location.

Incoming writes preserve location parts that are not mapped. Countries are translated between the systems. Unmatched or ambiguous countries are skipped; activity returns the affected Attio attribute IDs in `unmatched_attribute_ids`. Brevo's Country attribute is writable, while its detected location attributes are read-only. A missing or invalid location part, or a mapping that writes a detected attribute, returns `brevo_mapping_invalid`.

## Name-part mappings

Personal-name entries in attribute discovery carry `name_part`: `full_name`, `first_name`, or `last_name`. Send `attio_name_part` when mapping one of these values to a Brevo text attribute. The field is null for other mappings, and omitting it keeps earlier request behavior.

Full-name mappings remain outbound-only. First and last name can also be mapped into Attio from Brevo's own `FIRSTNAME` and `LASTNAME` attributes, using a writable, single-value Person name attribute. Read the attribute catalog's available directions before saving. Related-record name parts cannot be mapped into Attio; unsupported combinations return `brevo_mapping_invalid`.

## Activity and unsubscribe records

[Activity](https://neondeerdata.com/docs/api/brevo/activity/) records contact updates, list additions, and template sends, including changed attribute IDs, list or template IDs, and who started the action. Older entries may lack these fields. Activity responses do not include contact email addresses or the changed values.

[Unsubscribes and blocks](https://neondeerdata.com/docs/api/brevo/unsubscribes/) are different: this read returns email addresses so your organization can inspect recorded unsubscribes, complaints, hard bounces, and provider blocks. Entries may identify the affected list and currently linked Attio Person. Treat this response as personal data. Reading it does not send messages, resubscribe anyone, or remove restrictions.

Filter by one exact email address, without case sensitivity, or by reason. Continue using `pagination.next_cursor` until null. A cursor cannot be combined with other filters; send the cursor alone for subsequent pages.

## Message settings and reporting

Use [message activity settings and imports](https://neondeerdata.com/docs/api/brevo/messages/) to choose what reaches Attio Activities, inspect imports, and retry eligible work. A non-null `problem_message` explains what needs fixing; it is null when there is no reported problem. [SMS reporting settings](https://neondeerdata.com/docs/api/brevo/reporting/) cover the available SMS reporting options. These settings routes do not send messages. Use the separate [template-send operation](https://neondeerdata.com/docs/api/brevo/templates/) when you intend to send an email. The existing `include_subject` setting controls both the email subject and text copied into Attio Activities; it does not make message contents available through the public activity read.

## Status mappings and skipped values

Attribute discovery includes `kind: "status"`. Statuses map by title. `unmatched_attribute_ids` identifies statuses or countries that could not be matched. Nullable `reconnect_attribute_ids` identifies status attributes that need workspace access reconnected before new statuses can be added. Reconnect and review the affected attributes before retrying.

## Activity outcomes and repair

`unconfirmed` now describes only a template email whose send Brevo did not confirm. Failed or unfinished contact updates and list additions read `failed`; message events still waiting to reach Attio read `running`. Status filters and totals use the same meanings. Newly received message events carry the Person's `record_id`; earlier events may leave it null.

Skip reasons include `send_not_permitted`, `template_no_sender`, `not_delivered`, `not_allowed`, `workflow_off`, and `access_unchecked`. Read the returned reason before deciding what to retry. A template without a sender is covered by `brevo_template_not_found`.

Message settings can report `problem: "owned"` when another app owns the Attio Activity type, or `plan`, `payment`, and `key` when access needs attention. Use `problem_message` for the action to take. Accept future reason and problem values without crashing the client.

The portal can retry an eligible failed contact update, but there is no new public retry endpoint. For an unconfirmed email, check Brevo before starting another send.

## Attio action access and managed unsubscribe data

Admins can restrict record and bulk actions in Brevo settings. Attio workflows have separate switches. API keys and MCP connections retain their own permissions; these settings do not replace API authorization.

The organization's unsubscribe table uses the existing [lookup-table API](https://neondeerdata.com/docs/api/lookup-tables/). Its fill `kind` is `managed`: rows and supplied fields are maintained automatically. You can update your own fields on existing rows. Attempts to add managed rows return `operation_not_allowed`. An absent restriction is not proof of opt-in, and an unsubscribe applies only to its address.

## Filter discovery and exclusions

`GET /v1/brevo-integration/sync-attributes` and MCP `list_brevo_sync_attributes` list available filter attributes without their `options`. Send `attribute=<slug>` to fetch one attribute with its options. Use `search` to narrow by title or slug, and `object` for a related object's attributes. This is separate from contact-mapping attribute discovery and its `include_options` option.

Sync selections support `is_not` for compatible number, date, option, and record attributes, and `none_of` for record attributes. Negated comparisons exclude null, blank or whitespace-only text, and empty lists; use `empty` to select those values explicitly. Invalid conditions return `invalid_selection`, naming the attribute and object, with `param` pointing at the condition.

Activity can now report `record_not_found` as a skipped send or list addition when the Person no longer exists in Attio. Failed contact updates carry `not_completed` for an outbound update, or `attio_not_updated` for an incoming update. Review the reason before retrying.

## Protect existing Brevo values

The contact sync settings include `when_brevo_has_value`. Choose `always` to allow mapped updates to replace existing values, `keep_when_empty` to avoid replacing a value with a blank, or `fill_empty` to update only attributes that are empty in Brevo. Omitting the setting from an update keeps the saved choice. Read the current settings before changing the policy.

## Undo contact updates

[Contact update reads and undo actions](https://neondeerdata.com/docs/api/brevo/contacts/) let you inspect and undo supported Attio-to-Brevo contact updates. `list_brevo_activity` returns `undo` as `available`, `undone`, or `expired` for updates with a backup, and null for other activity.

Read `GET /v1/brevo-integration/activity/{update_id}/changes` or MCP `get_brevo_contact_update_changes`. It identifies changed Brevo attributes and their undo outcomes, not the before-and-after values; inspect those values in Neon Deer. Check `available` before proceeding.

Use `POST /v1/brevo-integration/activity/{update_id}/undo` or `restore_brevo_contact_update`. Supply `attributes` to restore selected Brevo attributes, or omit it for all attributes changed by that update. An attribute edited in Brevo since the update is left unchanged. The request returns `202` with `queued: true`; follow the changes read for each attribute's `restored`, `changed`, or `failed` outcome.

To undo a completed update of all contacts, use `POST /v1/brevo-integration/sync-runs/{run_id}/undo` or `restore_brevo_sync_run`, then follow `get_brevo_sync_run`. Its `undo` details include progress and outcomes. These MCP undo actions ask the connected person to confirm. They require `brevo:execute`; a queued run or undo stops making further writes if the key loses access.

Undo changes Brevo, not Attio. A later Attio edit can send the newer values again, and Brevo automations may respond to restored values. Updates without a backup, including older updates, cannot be undone. Use the returned availability rather than assuming every update remains eligible.

## Subscription restriction scopes

Brevo's current status determines whether an address remains restricted. `list_brevo_unsubscribes` returns the current restriction per address and scope, with stable IDs when contacts are checked again. The reason filter applies to the current restriction, not historical activity events. This list contains only restrictions reported by Brevo.

`all_marketing_email` covers marketing-only restrictions. `all_email` covers a Brevo block that also prevents transactional email. Restrictions can be released when Brevo reports the address is open again; that does not alter another address on the same Person. Manage subscription choices in Brevo rather than treating a missing restriction as consent.

The Attio status now says **No restriction recorded** instead of **Subscribed**, and **Status not confirmed** when Brevo's status cannot be read. Update Attio filters and workflows that compare the earlier label. These are app/Attio labels, not new API enum values.

When nobody selected can be emailed, MCP list additions and template sends return `422 invalid_selection` for `record_ids` before asking for confirmation. When only some can be emailed, the confirmation explains how many are eligible. Inspect the resulting operation for each Person's outcome.

## Add missing People from email activity

Contact synchronization still updates existing People; it does not create them. Email activity has a separate, optional Person-creation setting, off by default.

`get_brevo_message_settings` and `update_brevo_message_settings` expose `add_people`. It accepts `email.opened` and `email.clicked`; each selected event must also be in `events`, and event availability depends on the plan. Omitting `add_people` preserves the saved selection. Creation needs workspace access that can create Attio People. Invalid selections return `brevo_add_people_invalid`; missing access returns `brevo_add_people_access`, and settings may report `problem: "people"` with an explanation in `problem_message`.

For a waiting email activity, `list_brevo_activity` returns `add_person` as `available`, `adding`, `unconfirmed`, or null. Use `POST /v1/brevo-integration/activity/{activity_id}/person`, with an `Idempotency-Key`, or MCP `create_brevo_activity_person` with `request_key`. It requires `brevo:execute`. MCP asks the connected person to confirm. The action can be used even when automatic Person creation is off.

This adds a Person with the email address and Brevo's available first and last name, then attaches waiting activity for that address. It sends no email. An address held by a current or earlier Attio Person, or currently unsubscribed or blocked in Brevo, is refused. Imported earlier events never create People automatically.

The action returns `202`; follow the activity rather than assuming creation is complete. Handle `brevo_person_adding`, `brevo_person_add_refused`, `brevo_person_add_unconfirmed`, and `brevo_person_add_restricted`. MCP can also return confirmation-unavailable, confirmation-changed, or confirmation-declined errors. An unconfirmed result needs inspection; a returned `add_person` state controls whether a retry is offered. See the [activity reference](https://neondeerdata.com/docs/api/brevo/activity/) and [app guide](https://neondeerdata.com/docs/platform/brevo/#add-people).

## Run progress and stopped updates

`get_brevo_sync_run` now includes `stop`, null unless a saved mapping or filter stopped an update. It identifies `setting` as `mappings` or `filters`, a `problem`, and the affected mapping or filter when known. Fix the named setting before starting again. `problem: "changed"` means the settings were edited while the run was in progress; start a new run with the current settings.

Use the current [sync-run reference](https://neondeerdata.com/docs/api/brevo/contacts/) for the response fields and supported problem values. Contacts not reached when a run stops are skipped, not reported as failed writes.

The new Contacts and Runs views, per-run before-and-after values, and undo of chosen attributes across a run are available in Neon Deer. They do not add a public run-list or run-detail route. Public run undo retains its existing request body; selected-attribute undo for a single contact uses the separate contact-update operation.

## Retry Activities and contact updates

Use `POST /v1/brevo-integration/message-settings/retry` with an `Idempotency-Key`, or MCP `retry_brevo_activities` with `request_key`, to retry eligible message Activities and each Person's latest unsynced contact update. It requires `brevo:execute`; MCP asks for confirmation. This operation does not resend outgoing template emails. The API takes no activity filters or record selection; the filtered **Retry all** control in Neon Deer is a separate interface action.

The `202` response reports message Activities in `data.count`. `data.contact_updates` reports `queued` contact updates, `remaining` eligible updates, `waiting` updates already awaiting a retry, and `from_attio` actions that must be repeated from Attio. Call again if more remain. Follow Activity for the results; acceptance does not mean every update succeeded. Retries still use the current mappings, subscription checks, and identity checks.

A message Activity can fail with `reason: "not_saved"` when Attio has not confirmed it after repeated attempts. `retry_brevo_activities` can try it again. The app checks Attio and retries an unconfirmed Activity under the same write key to avoid creating a second copy. A historical `status: "outcome_unknown"` may represent an Activity already in Attio; inspect it rather than creating a fresh Activity yourself. This is distinct from an outgoing template email whose send is `unconfirmed`: check Brevo before starting another send.

A skipped list addition, template send, or contact update may return `confirming` while an earlier action for that address is checked. Wait and inspect its outcome before retrying. Contact updates that cannot be verified finish without holding later updates indefinitely. A later update checks the contact again. List additions and contact-creating actions must be repeated from Attio rather than through the contact-update retry.
