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

Parameter	Type	Required	Description
`contact_id`	Array of integers	No	Filter by contact ID. Repeatable.
`event_name`	Array of strings	No	Filter by event name. Repeatable.
`object_type`	Array of strings	No	Filter by object type. Repeatable.
`startDate`	String	No	Start 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`.
`endDate`	String	No	End of date range (YYYY-MM-DD or RFC3339). Required if `startDate` is set. Must be ≥ `startDate`.
`limit`	Integer	No	Max events to return. Default `100`, min `1`, max `10000`.
`offset`	Integer	No	Events 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 }

Field	Type	Description
`count`	Integer	Total count of events matching the filters. Use for pagination.
`events`	Array	List of matching events ordered by `event_date` descending.
`events[].contact_id`	Integer	Contact ID associated with the event.
`events[].event_date`	String	Date and time of the event (ISO 8601).
`events[].event_name`	String	Name of the event.
`events[].event_filter_id`	String	Filter ID of the event.
`events[].source`	String	Source of the event.
`events[].object_type`	String	Object type associated with the event.
`events[].event_properties`	Object	Event-level custom properties.
`events[].contact_properties`	Object	Contact-level properties at time of event.

Code	Description
`200`	List of events returned successfully.
`400`	Bad request — invalid parameters.
`401`	Unauthorized — 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

Field	Type	Required	Description
`event_name`	String	Yes	Name of the event. Limited to 255 characters; alphanumeric, `-`, `_` only.
`event_date`	String	No	ISO 8601 timestamp of when the event occurred. Defaults to creation time if omitted.
`identifiers`	Object	Yes	Contact identifier. At least one field is required.
`contact_properties`	Object	No	Contact attributes to update alongside the event (e.g. `"AGE": 37`).
`event_properties`	Object	No	Properties of the event. Supports strings, numbers, booleans, dates, nested objects. Keys limited to 255 characters; total size limited to 50 KB.

Response

Code	Description
`204`	Event created successfully. No content returned.
`400`	Bad request — invalid parameters.
`401`	Unauthorized — 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.

Limit	Value
Max events per request	200
Max request body size	512 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:

Field	Type	Required	Description
`event_name`	String	Yes	Name of the event. Limited to 255 characters; alphanumeric, `-`, `_` only.
`event_date`	String	No	ISO 8601 timestamp of when the event occurred. Defaults to creation time if omitted.
`identifiers`	Object	Yes	Contact identifier. At least one field is required.
`contact_properties`	Object	No	Contact attributes to update alongside the event.
`event_properties`	Object	No	Properties of the event. Supports strings, numbers, booleans, dates, nested objects. Keys limited to 255 characters; total size limited to 50 KB.
`object`	Object	No	Object 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:

Field	Description
`contact_id`	Internal Brevo contact ID. Takes priority over all other identifiers when present.
`email_id`	Contact email address.
`phone_id`	Contact SMS phone number.
`whatsapp_id`	Contact WhatsApp number.
`ext_id`	External contact ID.
`landline_number_id`	Contact landline number.

Object association

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

Field	Description
`object.type`	Type of object (e.g. `subscription`, `vehicle`).
`object.identifiers.id`	Internal object ID.
`object.identifiers.ext_id`	External object ID.

Response

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

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

Field	Type	Description
`message`	String	Confirmation message indicating the batch was accepted.
`count`	Integer	Number 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 }

Field	Type	Description
`status`	String	Status of the batch request.
`total_events`	Integer	Total number of events submitted.
`successful_events`	Integer	Number of events successfully processed.
`failed_events`	Integer	Number of events that failed.
`errors`	Array	List 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.

$	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'

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	}

$	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"
>	}
>	}'

$	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
>	}
>	}
>	]'

1	{
2	"message": "Batch accepted. Valid events have been added to the processing queue.",
3	"count": 7
4	}

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	}