Brevo
Connect Brevo to let Helios agents use its v3 API and start workflows from email, SMS and contact events.
What your agents can do
Agents search the Brevo v3 API and call endpoints using your connected credentials. They can manage contacts and lists, send transactional messages, create campaigns, read delivery reports, and update CRM companies, deals and tasks. Access depends on your Brevo plan and permissions.
Authentication
Brevo API key
In Brevo, open Settings > SMTP & API > API Keys and generate an API key. In Helios, choose Brevo API key and enter it in API key. Helios sends it in the api-key header and checks the connection with GET /account.
Your own Brevo app
Create a private, consent-based OAuth app in your Brevo organization using the Brevo app guide. Register the OAuth callback URL shown by Helios. Add all the scopes below to the app's configuration and upload it to Brevo.
Choose Your own Brevo app, enter Client ID and Client secret, then authorize access. Private apps can only be authorized within the organization that created them. This connection uses a private app with a client secret.
Helios requests both read and write for each resource below, for 34 scopes in total. Brevo does not mark any of these scopes as admin-only in its scope reference.
| Resource | Scopes |
|---|---|
| Account | account:read, account:write |
| Organization | organization:read, organization:write |
| Webhooks | webhooks:read, webhooks:write |
| Functions | brevo_functions:read, brevo_functions:write |
| Email campaigns | campaigns.email:read, campaigns.email:write |
| SMS campaigns | campaigns.sms:read, campaigns.sms:write |
| WhatsApp campaigns | campaigns.whatsapp:read, campaigns.whatsapp:write |
| Contacts | contacts:read, contacts:write |
| CRM | crm:read, crm:write |
| Conversations | conversations:read, conversations:write |
| Objects | objects:read, objects:write |
| Ecommerce | ecommerce:read, ecommerce:write |
| Events | events:read, events:write |
| Loyalty | loyalty:read, loyalty:write |
| Transactional email | transactional.email:read, transactional.email:write |
| Transactional SMS | transactional.sms:read, transactional.sms:write |
| Transactional WhatsApp | transactional.whatsapp:read, transactional.whatsapp:write |
Access tokens last one hour. Helios refreshes them when needed and schedules weekly refreshes to keep the 30-day refresh token active.
Triggers
Helios registers separate email and SMS webhooks for both transactional and marketing events. With an inbound domain, it also registers an inbound email webhook, for five webhooks in total. Each subscribes to every event supported by the /webhooks API for that type and channel. Brevo allows one webhook per URL and type, so SMS webhooks use the connection URL with ?channel=sms. Webhook requests carry a bearer token that Helios generates and verifies.
| Events | Meaning |
|---|---|
email.sent, email.delivered | Sending and successful delivery |
email.hard_bounced, email.soft_bounced | Permanent and temporary delivery failures |
email.blocked, email.rejected, email.deferred | Blocked, invalid or deferred messages |
email.marked_as_spam | A spam report |
email.opened, email.first_opened, email.clicked | Email engagement |
contact.unsubscribed | A contact unsubscribed |
contact.added_to_list, contact.updated, contact.deleted | Contact changes |
email.received | A parsed inbound message |
sms.sent, sms.accepted, sms.delivered | SMS sending, acceptance for delivery and successful delivery |
sms.replied | An SMS reply |
sms.soft_bounced, sms.hard_bounced | Temporary and permanent SMS delivery failures |
sms.unsubscribed | An SMS unsubscribe |
sms.skipped, sms.blacklisted, sms.rejected | SMS messages that were skipped, not sent to a blacklisted recipient, or rejected. sms.rejected is transactional only |
Brevo’s transactional error and invalid_email payloads both trigger email.rejected.
Recipient email accepts patterns such as *@example.com without case sensitivity. Tag and List ID filters apply when the delivery includes those fields. An empty filter accepts every value. A selected filter does not match a delivery that lacks that field.
SMS triggers use Recipient phone patterns against Brevo's to field. Campaign ID matches campaign_id in marketing SMS payloads. Tag is available for every SMS event except sent and blacklisted, whose payloads do not document a tag field. sms.rejected has no Campaign ID because it comes only from transactional SMS.
Inbound email
Both connection methods offer an optional Inbound domain. Set it to a verified receiving domain, such as reply.example.com, with the MX records required by Brevo inbound parsing. This must be different from your sending domain. Leave it empty to connect without inbound triggers. Helios deletes this connection’s existing inbound webhooks and reports email.received as unavailable with a setup reason.
Limits and errors
Brevo limits marketing and transactional webhooks to 40 per account. Helios reuses matching webhooks and creates replacements before deleting superseded ones. A failed replacement leaves the existing webhook in place. Plan, permission or configuration rejections appear as unavailable events with a reason only when no successful or retained authenticated subscription still delivers them.
The subscription catalog covers email, SMS and contact events supported by the /webhooks API. Brevo documents SMS subscribe (subscribe) payloads, but Helios knows no registration value for them, so that event is excluded. Proxy opens, coupon delivery and separate payment, loyalty, meeting, push, Sales CRM and Conversations hooks are also outside that API's registration enum. Their API operations remain available through the API index.
Outbound payloads usually identify the webhook rather than the individual delivery. Helios derives a retry ID from event details. The ID includes both ts_epoch and ts_event when present. Identical items within one batch receive stable occurrence suffixes, so retrying that batch keeps the same IDs. Otherwise identical events in separate batches with the same timestamps can still be treated as one. Inbound messages use Brevo's recipient UUIDs.
If OAuth returns invalid_scope, check that all 34 scopes are registered on your app. A rejected API key or expired authorization requires updating the connection credentials. File upload and download operations are included in the API index. Agents use curl for presigned file transfers.
See the API reference and webhook guide for provider limits and payload details.
Last updated on