Brevo tracker and eventsEvents

Event endpoints

Create individual or batched events to track contact interactions via the Events API.

Create an event

POST /events creates a single event to record a contact’s interaction.

cURL
$curl --request POST \
>     --url https://api.brevo.com/v3/events \
>     --header 'accept: application/json' \
>     --header 'api-key: YOUR_API_KEY' \
>     --header 'content-type: application/json' \
>     --data '{
>  "event_name": "video_played",
>  "event_date": "2024-02-06T20:59:23.383Z",
>  "identifiers": {
>    "email_id": "jane.doe@example.com"
>  },
>  "contact_properties": {
>    "AGE": 32,
>    "GENDER": "FEMALE"
>  },
>  "event_properties": {
>    "video_title": "Brevo — The most approachable CRM suite",
>    "video_description": "Create your free account today!",
>    "duration": 142,
>    "autoplayed": false,
>    "upload_date": "2023-11-24T12:09:10+01:00"
>  }
>}'

Request body

FieldTypeRequiredDescription
event_nameStringYesName of the event. Limited to 255 characters; alphanumeric, -, _ only.
event_dateStringNoISO 8601 timestamp of when the event occurred. Defaults to creation time if omitted.
identifiersObjectYesContact identifier. At least one field is required.
contact_propertiesObjectNoContact attributes to update alongside the event (e.g. "AGE": 37).
event_propertiesObjectNoProperties of the event. Supports strings, numbers, booleans, dates, nested objects. Keys limited to 255 characters; total size limited to 50 KB.

Response

CodeDescription
204Event created successfully. No content returned.
400Bad request — invalid parameters.
401Unauthorized — missing or invalid API key.

Create events in batch

POST /events/batch sends multiple events in a single request. Use this endpoint to reduce API calls when tracking many interactions at once.

LimitValue
Max events per request200
Max request body size512 KB
cURL
$curl --request POST \
>     --url https://api.brevo.com/v3/events/batch \
>     --header 'accept: application/json' \
>     --header 'api-key: YOUR_API_KEY' \
>     --header 'content-type: application/json' \
>     --data '[
>  {
>    "event_name": "order_created",
>    "event_date": "2024-02-06T20:59:23.383Z",
>    "identifiers": {
>      "email_id": "jane.doe@example.com"
>    },
>    "contact_properties": {
>      "AGE": 32,
>      "GENDER": "FEMALE"
>    },
>    "event_properties": {
>      "order_id": "ORD-1234",
>      "total": 89.99
>    },
>    "object": {
>      "type": "subscription",
>      "identifiers": {
>        "ext_id": "sub-59374-linwn"
>      }
>    }
>  },
>  {
>    "event_name": "video_played",
>    "identifiers": {
>      "contact_id": 211
>    },
>    "event_properties": {
>      "video_title": "Getting started with Brevo",
>      "duration": 95
>    }
>  }
>]'

Request body

The request body is an array of event objects. Each object supports the following fields:

FieldTypeRequiredDescription
event_nameStringYesName of the event. Limited to 255 characters; alphanumeric, -, _ only.
event_dateStringNoISO 8601 timestamp of when the event occurred. Defaults to creation time if omitted.
identifiersObjectYesContact identifier. At least one field is required.
contact_propertiesObjectNoContact attributes to update alongside the event.
event_propertiesObjectNoProperties of the event. Supports strings, numbers, booleans, dates, nested objects. Keys limited to 255 characters; total size limited to 50 KB.
objectObjectNoObject record associated with the event. Ignored if the object type or identifier does not exist on the account.

Identifiers

Each event must include at least one of the following contact identifiers:

FieldDescription
contact_idInternal Brevo contact ID. Takes priority over all other identifiers when present.
email_idContact email address.
phone_idContact SMS phone number.
whatsapp_idContact WhatsApp number.
ext_idExternal contact ID.
landline_number_idContact landline number.

Object association

Use the object field to associate an event with a Custom Object record:

FieldDescription
object.typeType of object (e.g. subscription, vehicle).
object.identifiers.idInternal object ID.
object.identifiers.ext_idExternal object ID.

Response

This endpoint supports partial success. If some events fail validation, the API returns 207 with a per-event breakdown.

CodeDescription
204All events processed successfully. No content returned.
207Partial success — some events failed. See response body for details.
400Bad request — all events failed validation.
401Unauthorized — missing or invalid API key.

207 / 400 response body

1{
2  "status": "partial_success",
3  "total_events": 3,
4  "successful_events": 2,
5  "failed_events": 1,
6  "errors": [
7    {
8      "eventIndex": [2],
9      "message": "event_name is required"
10    }
11  ]
12}
FieldTypeDescription
statusStringStatus of the batch request.
total_eventsIntegerTotal number of events submitted.
successful_eventsIntegerNumber of events successfully processed.
failed_eventsIntegerNumber of events that failed.
errorsArrayList of errors. Each entry contains eventIndex (0-based array of failed event positions) and message.

Events that pass validation are processed even when others in the same batch fail. Validated events are not rolled back if other events in the batch fail.