Brevo tracker and eventsEvents

Event endpoints

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

Get events

GET /events retrieves a list of events filtered by various criteria.

cURL
$curl --request GET \
>     --url 'https://api.brevo.com/v3/events?event_name=order_created&limit=100&offset=0' \
>     --header 'accept: application/json' \
>     --header 'api-key: YOUR_API_KEY'

Query parameters

ParameterTypeRequiredDescription
contact_idArray of integersNoFilter by contact ID. Repeatable.
event_nameArray of stringsNoFilter by event name. Repeatable.
object_typeArray of stringsNoFilter by object type. Repeatable.
startDateStringNoStart of date range (YYYY-MM-DD or RFC3339). Required if endDate is set. Defaults to 6 months ago when both are omitted. Must be ≤ endDate.
endDateStringNoEnd of date range (YYYY-MM-DD or RFC3339). Required if startDate is set. Must be ≥ startDate.
limitIntegerNoMax events to return. Default 100, min 1, max 10000.
offsetIntegerNoEvents to skip for pagination. Default 0.

Response (200)

1{
2  "count": 2,
3  "events": [
4    {
5      "contact_id": 211,
6      "event_date": "2024-02-06T20:59:23.383Z",
7      "event_name": "order_created",
8      "event_filter_id": "abc123",
9      "source": "api",
10      "object_type": "subscription",
11      "event_properties": {
12        "duration": 142,
13        "video_title": "Brevo — The most approachable CRM suite"
14      },
15      "contact_properties": {
16        "AGE": 32,
17        "GENDER": "FEMALE"
18      }
19    }
20  ]
21}
FieldTypeDescription
countIntegerTotal count of events matching the filters. Use for pagination.
eventsArrayList of matching events ordered by event_date descending.
events[].contact_idIntegerContact ID associated with the event.
events[].event_dateStringDate and time of the event (ISO 8601).
events[].event_nameStringName of the event.
events[].event_filter_idStringFilter ID of the event.
events[].sourceStringSource of the event.
events[].object_typeStringObject type associated with the event.
events[].event_propertiesObjectEvent-level custom properties.
events[].contact_propertiesObjectContact-level properties at time of event.
CodeDescription
200List of events returned successfully.
400Bad request — invalid parameters.
401Unauthorized — missing or invalid API key.

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
202All events accepted and queued for processing. Returns { message, count }.
207Partial success — some events failed. See response body for details.
400Bad request — all events failed validation.
401Unauthorized — missing or invalid API key.

202 response body

1{
2  "message": "Batch accepted. Valid events have been added to the processing queue.",
3  "count": 7
4}
FieldTypeDescription
messageStringConfirmation message indicating the batch was accepted.
countIntegerNumber of events queued for processing.

207 / 400 response body

1{
2  "status": "partiallyQueued",
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.