Brevo API
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 to connect the accounts.
Contact mappings and sync
Use contact mappings and synchronization 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 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 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.
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 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 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 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 cover the available SMS reporting options. These settings routes do not send messages. Use the separate template-send operation 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. 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 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 and app guide.
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 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.