Documentation CRM Brevo

CRM integration

Brevo

Brevo integration overview
  • CategoryCRM
  • AuthAPI key

Overview

Brevo (formerly Sendinblue) connects on /integrations in the dashboard. Click the Brevo card and the 'Connect Brevo' modal asks for your Brevo v3 API key (any key that starts with 'xkeysib-'). Once saved, MessageMind runs a three-tier two-way sync against the key: webhook-driven live updates for existing contact edits, an hourly poll scoped to newly created Brevo contacts, and a full reconciliation poll every 7 days as a safety net. The sync keeps contacts, labels (one Brevo list per label value under a dedicated 'MessageMind' folder) and custom fields (Brevo attributes) in step in both directions. Brevo is treated as a contact sync rather than the AI's primary data source, so it can sit alongside another connected CRM on the same tenant.

What MessageMind can do with it

  • Bring every Brevo contact into MessageMind on the first sync and keep them in step with incremental updates afterwards.
  • Mirror MessageMind labels into Brevo as lists (grouped under a dedicated 'MessageMind' folder), and recognize list changes made in Brevo.
  • Map MessageMind custom fields to Brevo attributes and create missing attributes on demand with the correct type.
  • Carry secondary emails, secondary phones, address, note, source, language, time zone and date of birth as Brevo attributes when Brevo has no native field for them.
  • Register a marketing webhook so contact updates, list additions, contact deletions and unsubscribes reach MessageMind in real time.
  • Pick up newly created Brevo contacts on an hourly poll scoped to brevoCreatedSince, in case the webhook was down when the contact was created.
  • Fall back to a full reconciliation poll (default every 7 days, BREVO_POLL_INTERVAL_DAYS) that catches anything the webhook missed.
  • Detect echoes: a change MessageMind pushed to Brevo that comes back as a webhook is suppressed inside a 30-second window instead of being re-ingested.
  • Sit alongside another connected CRM (Salesforce, HubSpot, webCRM) without conflicting; Brevo is marked as an independent connection.

Requirements

  • A Brevo account with permission to generate a v3 API key under SMTP & API > API Keys. The key must start with 'xkeysib-'.
  • If Brevo's Authorised IPs feature is on, the MessageMind server IP must be allowed on the key or the API will refuse the request.
  • A publicly reachable MessageMind base URL is required for live updates. Without one, MessageMind still runs the scheduled poll but cannot register a webhook.

How to connect

  1. In Brevo, open SMTP & API, API Keys and click 'Generate a new API key'. v3 keys start with 'xkeysib-'. Copy the value.
  2. If your Brevo account uses Authorised IPs on the key, add the MessageMind server IP under Brevo, Settings, Security, Authorised IPs so the key passes IP checks.
  3. In the MessageMind dashboard, open /integrations and click the Brevo card. The 'Connect Brevo' modal opens with the description about the three-tier two-way sync.
  4. Paste the key into the field labelled 'API Key' (type: password) and click Integrate. MessageMind calls Brevo's /account endpoint to validate the key, read your account email and company name, and open the connection.
  5. On a successful connect, MessageMind registers a marketing webhook with Brevo (secured by a per-integration secret in a custom header plus a bearer token, since Brevo does not sign payloads) and queues the initial full sync. The dashboard card flips to Connected and the hourly new-contact poll plus the 7-day reconcile start running in the background.

Authentication and permissions

Mechanism
Brevo v3 API key sent as the 'api-key' header on every call to api.brevo.com. The inbound webhook is authenticated by a per-integration shared secret that Brevo echoes back on every delivery (custom header plus bearer token), since Brevo does not sign payloads.
Credentials
A single Brevo v3 API key, stored on your MessageMind tenant under the 'API Key' label, together with a server-minted webhook token and webhook secret used only for the inbound path.

Available data and actions

Reads

  • Brevo account profile (email, company name, account identifier) to confirm the key and record which account the connection belongs to.
  • Brevo contacts, paged (up to 1000 per page), with modifiedSince / createdSince filters for incremental runs.
  • A single Brevo contact by email, external id or phone, read by the webhook drain to fetch the latest state of a changed contact.
  • Brevo contact attributes (the full list) to understand which Brevo attributes exist and their types.
  • Brevo lists and folders, used to pair MessageMind labels with Brevo lists under the dedicated folder.
  • Brevo webhooks registered on the account, used to detect, adopt or replace an existing registration.

Writes

  • Create or update a Brevo contact (upsert) with primary email, SMS phone, first/last name, and a mapped set of attributes.
  • Update an existing Brevo contact by Brevo contact id.
  • Create missing Brevo attributes on demand (secondary emails, secondary phones, date of birth, address parts, note, source, language, time zone, and any mapped custom field).
  • Create a Brevo folder named 'MessageMind' (or the configured folder name) and create lists inside it for MessageMind labels.
  • Register, update or delete the inbound marketing webhook with the events contactUpdated, listAddition, contactDeleted and unsubscribed.
  • Record opt-outs locally when Brevo delivers an unsubscribed event, and unlink a MessageMind contact when Brevo delivers a contactDeleted event.

AI agent use cases

  • Keep your Brevo contact database and MessageMind's view of the same people in step without manual CSV imports.
  • Let the AI apply a MessageMind label (for example a lifecycle stage) and have the matching Brevo list membership update automatically.
  • Give the marketing team one place in Brevo for every MessageMind-captured contact, with secondary emails and phones carried as attributes rather than lost.
  • React to unsubscribes made in Brevo by marking the MessageMind contact opted-out immediately, so the AI stops reaching out through that channel.

Configuration

  • Lists MessageMind creates for labels are grouped inside a Brevo folder (default name 'MessageMind'). You can change the folder name through the server environment.
  • The reconciliation poll runs every 7 days by default (BREVO_POLL_INTERVAL_DAYS, 1 to 60) and reads changes with a short modifiedSince overlap to tolerate clock skew.
  • The new-contacts poll runs hourly and uses brevoCreatedSince to pick up only Brevo contacts whose creation the webhook missed. A failed row keeps the created-since window where it was so the next hour re-reads it.
  • The initial sync pulls the whole account (treated as 'the import'); subsequent runs only fetch deltas.
  • Custom field names are mangled to legal Brevo attribute names (uppercase, underscores, up to 50 characters). The mapping is deterministic in both directions.
  • Secondary emails and phones travel as the attributes MM_SECONDARY_EMAILS and MM_SECONDARY_PHONES because Brevo has no native secondary identifier fields.
  • Date of birth travels as the DATE_OF_BIRTH attribute (created on demand), since Brevo has no native birthday field.
  • A tag whose variables have no value is not sent, so empty attributes do not overwrite real values in Brevo.
  • Rate-limited to around 8 requests per second per key, keeping within Brevo's published 10 req/s ceiling on /contacts.
  • An echo window of 30 seconds suppresses webhook events triggered by MessageMind's own writes.

Example workflows

Initial import and incremental catch-up

  1. You connect Brevo in MessageMind. The key is validated against /account and the account email and company name are stored.
  2. The marketing webhook is registered against your MessageMind base URL, secured with a per-integration secret.
  3. The initial sync pulls every Brevo contact and attribute, pairs lists with MessageMind labels, and creates linked contacts.
  4. Afterwards the webhook pushes edits in real time, the hourly new-contact poll picks up any contact Brevo created while the webhook was down, and the 7-day reconcile closes the gap on edits the webhook missed.

Unsubscribe in Brevo propagates to MessageMind

  1. A contact unsubscribes in Brevo (or marks a Brevo send as spam).
  2. Brevo delivers an 'unsubscribed' event to the MessageMind webhook, authenticated by the per-integration secret.
  3. MessageMind records the opt-out on the matching contact so campaigns and the AI respect it.

Limitations

  • Brevo cannot sign payloads, so the inbound webhook is authenticated by a shared secret and (optionally) IP range checks against Brevo's published egress ranges.
  • Brevo has no native secondary email, secondary phone or birthday field: these travel as text / date attributes that MessageMind creates on demand.
  • Deliveries carrying more than 500 events in one POST are capped to protect the receiver.
  • A key with IP restrictions turned on fails validation if the MessageMind server IP is not on the allow list. Brevo's own message is surfaced in the connection error.
  • Live updates require a public MessageMind base URL. On a tunnel or private host, the webhook is not registered and inbound sync runs on the poll alone.
  • A key regenerated inside Brevo invalidates the connection until the new key is pasted into MessageMind.

Troubleshooting

The connect form says the API key is invalid.

A valid Brevo v3 key starts with 'xkeysib-'. Create a v3 key in Brevo under SMTP & API > API Keys and paste it back into the connection form.

Brevo rejected the request from the MessageMind server IP.

The key has IP restrictions turned on. Add the MessageMind server IP under Brevo > Settings > Security > Authorised IPs (or turn the IP restriction off for the key), then connect again.

Live updates are not reaching MessageMind.

Confirm your MessageMind base URL is public (not localhost or a private host). If it is public, open the Brevo integration status to see the last recorded webhook error and whether the webhook is registered; a rotate of the webhook secret re-registers the subscription.

A list change made in Brevo is not reflected in MessageMind.

Brevo's list_addition event drives label changes on the MessageMind side. Confirm the list sits inside the 'MessageMind' folder (or the configured folder name) and that its name matches an owner label template. Lists outside that folder are treated as campaign audiences and are left alone.

Disconnect and reconnect

  • On /integrations in the dashboard, open the Brevo card and click Disconnect. MessageMind stops the Brevo sync jobs, deletes the registered webhook from Brevo and clears every stored Brevo link from your contacts.
  • The Brevo account itself keeps its contacts, lists and attributes. Disconnecting does not delete anything on Brevo's side (the 'MessageMind' folder stays).
  • To reconnect, paste a Brevo v3 API key into the connection form. If you reconnect to a different Brevo account, MessageMind clears the old links and checkpoints and starts a fresh initial sync.