> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developers.brevo.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.brevo.com/_mcp/server. # Event endpoints ## Get events `GET /events` retrieves a list of events filtered by various criteria. ```bash title="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) ```json { "count": 2, "events": [ { "contact_id": 211, "event_date": "2024-02-06T20:59:23.383Z", "event_name": "order_created", "event_filter_id": "abc123", "source": "api", "object_type": "subscription", "event_properties": { "duration": 142, "video_title": "Brevo — The most approachable CRM suite" }, "contact_properties": { "AGE": 32, "GENDER": "FEMALE" } } ] } ``` | 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. ```bash title="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 | ```bash title="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 ```json { "message": "Batch accepted. Valid events have been added to the processing queue.", "count": 7 } ``` | Field | Type | Description | | :-------- | :------ | :------------------------------------------------------ | | `message` | String | Confirmation message indicating the batch was accepted. | | `count` | Integer | Number of events queued for processing. | #### 207 / 400 response body ```json { "status": "partiallyQueued", "total_events": 3, "successful_events": 2, "failed_events": 1, "errors": [ { "eventIndex": [2], "message": "event_name is required" } ] } ``` | 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.