---
title: "Send an event"
description: "Records that a contact did something in your product. The event starts every live automation whose trigger names it and moves on anybody who was waiting for it."
url: "https://openemail.uk/docs/api/automations/events"
area: "API"
category: "Mailbox"
---

# Send an event

Records that a contact did something in your product. The event starts every live automation whose trigger names it and moves on anybody who was waiting for it.

`POST /events`

**Also documents:** `POST /events/batch`

## POST /events

Records that a contact did something in your product. The event starts every live automation whose trigger names it and moves on anybody who was waiting for it.

## Example

Needs `contacts:write`. Name the contact by `email` or by `contactId`.

**curl**

```
curl -X POST "$OE/events" -H "$AUTH" -H 'content-type: application/json' -H 'Idempotency-Key: order-A-1042' -d '{
  "name": "order.placed",
  "email": "ana@example.com",
  "properties": { "orderId": "A-1042", "total": 59 },
  "createContact": true
}'
```

**Response**

```
{
  "object": "contact_event",
  "id": "cev_6a1d9f3c8b2e40a75d9c1e38",
  "contactId": "5b0e7c1a-2f4d-4c8b-9a36-1e7d0c5f8b24",
  "email": "ana@example.com",
  "name": "order.placed",
  "properties": { "orderId": "A-1042", "total": 59 },
  "occurredAt": "2026-10-11T08:02:03.000Z",
  "mode": "live",
  "createdAt": "2026-10-11T08:02:03.412Z",
  "replayed": false,
  "enrolled": ["aut_7c2e9a1f4b8d30c65e1a9f27"],
  "resumed": 0
}
```

> `name` is up to 100 letters, digits, dots, colons, dashes and underscores, starting with a letter or a digit. Names are case-sensitive.

> `properties` holds at most 50 keys and 4 KB of JSON. A trigger filter, an email value and a branch can read them.

> `occurredAt` defaults to now. It may lie up to 90 days in the past and no more than 5 minutes in the future.

> An unknown address answers 404 `contact_not_found` unless `createContact` is true, which adds the contact, with `contactName` as its name.

> `enrolled` lists the automations the contact entered and `resumed` counts the waits the event ended.

> Sending the same `Idempotency-Key` again answers 200 with the first event and `replayed: true`. The same key with a different body is refused with 422 `idempotency_key_reuse`.

> An event sent with a test key is stored with `mode: "test"` and starts nothing.

## Batch

`POST /events/batch` takes up to 100 events in `events`, each shaped like the body above. It answers 200 even when some are refused, and says which.

**curl**

```
curl -X POST "$OE/events/batch" -H "$AUTH" -H 'content-type: application/json' -d '{
  "events": [
    { "name": "order.placed", "email": "ana@example.com" },
    { "name": "order.placed", "email": "nobody@example.com" }
  ]
}'
```

**Response**

```
{
  "object": "contact_event_batch",
  "accepted": [{ "index": 0, "object": "contact_event", "id": "cev_6a1d9f3c8b2e40a75d9c1e38", "…": "…" }],
  "failed": [{ "index": 1, "code": "contact_not_found", "message": "No contact with that address. Pass createContact: true to add one." }]
}
```

> `index` is the position of the event in the array you sent.

> A key or app may send 600 events a minute. After that the answer is 429 `event_rate_limited`.

## Reference

- [`POST /events`](https://openemail.uk/docs/api/reference/events#post-events): full reference
- [`POST /events/batch`](https://openemail.uk/docs/api/reference/events#post-events-batch): full reference