> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sendrealm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Events

> Send customer events, understand system events, and trigger automations.

Sendrealm supports two event categories:

* Customer events that you submit, like `order.completed`
* Reserved system events under the `sendrealm.` namespace

## Customer event rules

* Must not start with `sendrealm.`
* Must use lowercase dot-separated names
* Each audience may include underscores

Examples:

* `order.completed`
* `billing.payment_failed`
* `user.onboarded`

## System events

Examples of platform-generated events:

* `sendrealm.mail.send`
* `sendrealm.mail.delivery`
* `sendrealm.mail.open`
* `sendrealm.push.send`
* `sendrealm.push.open`
* `sendrealm.contact.created`
* `sendrealm.audience.entered`
* `sendrealm.topic.subscribed`

## Event identity resolution

When Sendrealm receives an event, it resolves the contact identity in this order:

1. `contact_id`
2. `external_id`
3. normalized `email`

That same identity resolution is used when matching `wait_for_event` automation steps.

## Example request

```bash theme={null}
curl https://api.sendrealm.com/events \
  -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "order.completed",
    "email": "olivia@example.com",
    "payload": {
      "order_id": "ord_123",
      "amount": 4900,
      "currency": "USD"
    },
    "occurred_at": "2026-06-08T14:15:00.000Z",
    "idempotency_key": "evt_order_completed_ord_123"
  }'
```

New customer events are accepted with `202 Accepted`. If you resend the same `idempotency_key`, Sendrealm returns the existing event instead of creating a duplicate.

## Delivery guarantees

* Event ingest is at-least-once, not exactly-once.
* Sendrealm deduplicates by `project_id + idempotency_key`.
* Retries use exponential backoff before an event is moved to the dead-letter queue.
* Event ordering is best effort only. Do not assume two separate events arrive or execute in strict sequence.

## Payload and governance

* Event payloads are limited by the project policy `event_payload_limit_bytes`.
* Sendrealm stores schema hints and redacted example payloads in the event catalog for debugging.
* The dashboard lets project owners review the event catalog, inspect example payloads, and confirm which events are currently flagged for likely PII.
* Backoffice tooling can filter the event catalog by event name, source, and PII detection to investigate schema drift faster.
* Backoffice observability also tracks average event-processing latency so you can distinguish queue lag from bad payloads.
* Reserved `sendrealm.*` system events are emitted by the platform and cannot be submitted by customers.

## Retention

* Event retention is controlled per project.
* The default window is 90 days unless your project policy overrides it.

## Related pages

* [Events API](/api-reference/endpoint/events)
* [Automations](/tutorials/automations)