# Send events from your backend

> Record workspace and custom events from your servers with the Events API, one at a time or in batches, with an Events Only API key.

Send events from your servers for anything that must not depend on the visitor's browser, such as orders, payments, subscription changes or events from a back office. This page shows how to send one event, how to send many, and how to handle errors.

## Before you begin

- Sending events is included with Pro, Business and Custom plans. A Pro workspace can use 100 event types and a Business workspace 1,000. See [Limits](/docs/events/#limits).
- Create an API key with the **Events Only** scope in **Email API → API Keys**. It can send events and nothing else: it can't read your data, manage event definitions or send email. A **Full Access** key works too. See [API keys](/docs/developers/api-keys/#scopes).
- To send workspace events, [define them](/docs/events/workspace-events/) first. Custom events need no setup.

## Send an event

Call [Send an event](/docs/api-reference/events/send/) with the event's `type`, its `properties` and the person it's about:

```bash
curl -X POST https://api.emailit.com/v2/events \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "c:order.completed",
    "email": "jane@example.com",
    "properties": { "order_id": "1001", "total": 59.9, "currency": "EUR" },
    "occurred_at": "2026-10-19T09:30:00Z"
  }'
```

- `email` ties the event to the contact with that address. If you already know the contact's ID, send `contact_id` instead.
- `occurred_at` is when it happened, for example when you send events from a queue. Leave it out to use the current time.
- The response is `201` with the stored event and its `evt_` ID. An Events Only key gets the event back without `data`.

## Send many events at once

[Send events in a batch](/docs/api-reference/events/batch/) takes up to 100 events in one request, which suits imports and scheduled syncs:

```bash
curl -X POST https://api.emailit.com/v2/events/batch \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      { "type": "c:order.completed", "email": "jane@example.com", "properties": { "order_id": "1001", "total": 59.9 } },
      { "type": "c:order.completed", "email": "omar@example.com", "properties": { "order_id": "1002", "total": 18 } }
    ]
  }'
```

A batch is all or nothing: if one event is invalid, none is stored. The `422` response lists each problem under `events.<index>`, so you can fix or drop those events and send the batch again.

## Handle errors

| Status | Meaning | What to do |
| --- | --- | --- |
| `201` | Stored. | Nothing. |
| `400` | The body isn't a JSON object, or the batch is empty or has more than 100 events. | Fix the request. |
| `401` | The API key is missing or wrong. | Check the key. |
| `403` | The key's scope can't send events, or the workspace is on Pay as you go (`"error": "plan_required"`). | Use an Events Only or Full Access key, or upgrade to Pro or Business. |
| `422` | An event is invalid: a `w:` event that isn't defined, a property of the wrong type, an unknown `contact_id`, a date more than 24 hours ahead, or a new event type when the workspace already uses its plan's number of types. `errors` names each field. | Fix the event, or upgrade for more event types. Retrying it unchanged fails again. |
| `5xx` | A temporary problem on Emailit's side. | Retry with backoff. |

Events have no idempotency key, so retrying a request that went through stores the event twice. Put your own ID in the properties, such as `order_id`, so whoever reads the events can recognize duplicates.

## Check that events arrive

Open **Email API → Events**. The **Log** tab lists new events at the top; set **Scope** to **Custom** or **Workspace** to hide system events. Select an event to see its properties, the contact it belongs to and where it came from. Events tied to a contact also show in the contact's **Activity log**.

## Related

  - [Event tracking](/docs/events/): Scopes, names and where events go.
  - [Tracking script](/docs/events/tracking-script/): Send events from your website.
  - [Send an event](/docs/api-reference/events/send/): Every parameter and response.
  - [API keys](/docs/developers/api-keys/): Create an Events Only key.

---
Source: https://emailit.com/docs/events/send-events/