Event Ingest

Ingest an event

curl --request POST \
  --url https://api.sendrealm.com/events \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "event": "order.completed",
  "contact_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "email": "jsmith@example.com",
  "external_id": "<string>",
  "payload": {},
  "contact": {
    "fields": {}
  },
  "occurred_at": "2023-11-07T05:31:56Z",
  "idempotency_key": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    event: 'order.completed',
    contact_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    email: 'jsmith@example.com',
    external_id: '<string>',
    payload: {},
    contact: {fields: {}},
    occurred_at: '2023-11-07T05:31:56Z',
    idempotency_key: '<string>'
  })
};

fetch('https://api.sendrealm.com/events', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.sendrealm.com/events"

payload = {
    "event": "order.completed",
    "contact_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "email": "jsmith@example.com",
    "external_id": "<string>",
    "payload": {},
    "contact": { "fields": {} },
    "occurred_at": "2023-11-07T05:31:56Z",
    "idempotency_key": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "event": "<string>",
    "deduplicated": true,
    "occurred_at": "2023-11-07T05:31:56Z"
  }
}

{
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "event": "<string>",
    "resolved_identity_value": "<string>",
    "occurred_at": "2023-11-07T05:31:56Z"
  }
}

{
  "status": 123,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": null
  }
}

{
  "status": 123,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": null
  }
}

POST

events

Ingest an event

curl --request POST \
  --url https://api.sendrealm.com/events \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "event": "order.completed",
  "contact_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "email": "jsmith@example.com",
  "external_id": "<string>",
  "payload": {},
  "contact": {
    "fields": {}
  },
  "occurred_at": "2023-11-07T05:31:56Z",
  "idempotency_key": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    event: 'order.completed',
    contact_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    email: 'jsmith@example.com',
    external_id: '<string>',
    payload: {},
    contact: {fields: {}},
    occurred_at: '2023-11-07T05:31:56Z',
    idempotency_key: '<string>'
  })
};

fetch('https://api.sendrealm.com/events', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.sendrealm.com/events"

payload = {
    "event": "order.completed",
    "contact_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "email": "jsmith@example.com",
    "external_id": "<string>",
    "payload": {},
    "contact": { "fields": {} },
    "occurred_at": "2023-11-07T05:31:56Z",
    "idempotency_key": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "event": "<string>",
    "deduplicated": true,
    "occurred_at": "2023-11-07T05:31:56Z"
  }
}

{
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "event": "<string>",
    "resolved_identity_value": "<string>",
    "occurred_at": "2023-11-07T05:31:56Z"
  }
}

{
  "status": 123,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": null
  }
}

{
  "status": 123,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": null
  }
}

Endpoint

POST /events

Request body

{
  "event": "order.completed",
  "contact_id": "c671f89b-3ec1-4c58-9ad2-4ef8c2917cda",
  "payload": {
    "order_id": "ord_123",
    "total": 4900
  },
  "correlation": {
    "key": "order_id",
    "value": "ord_123"
  },
  "occurred_at": "2026-06-08T14:15:00.000Z",
  "idempotency_key": "evt_order_completed_ord_123"
}

You can also identify a contact with external_id or email. Use correlation when an identity can have more than one active business flow. For checkout recovery, send the same checkout_id with both checkout.started and checkout.completed; a correlated wait resumes only its matching checkout. To create or merge an email contact while ingesting an event, opt in explicitly:

{
  "event": "checkout.started",
  "email": "olivia@example.com",
  "contact": {
    "mode": "upsert",
    "fields": {
      "first_name": "Olivia"
    }
  }
}

Without contact.mode: "upsert", event ingestion resolves existing contacts only. Identity resolution order is:

contact_id
external_id
normalized email

Successful response

{
  "data": {
    "id": "4d978da0-4504-42e3-9d71-e9b9a2f9082d",
    "event": "order.completed",
    "resolved_identity_type": "contact_id",
    "resolved_identity_value": "c671f89b-3ec1-4c58-9ad2-4ef8c2917cda",
    "occurred_at": "2026-06-08T14:15:00.000Z"
  }
}

New customer events currently return 202 Accepted.

Idempotent replay response

If you reuse the same idempotency_key, Sendrealm returns the existing event instead of creating a new one:

{
  "data": {
    "id": "4d978da0-4504-42e3-9d71-e9b9a2f9082d",
    "event": "order.completed",
    "deduplicated": true,
    "occurred_at": "2026-06-08T14:15:00.000Z"
  }
}

Reserved namespace

Customer-submitted events must not start with sendrealm.. Examples of Sendrealm system events:

sendrealm.mail.delivery
sendrealm.push.open
sendrealm.contact.updated
sendrealm.topic.subscribed

Guarantees and limits

Event ingest is at-least-once.
Idempotency is enforced by project_id + idempotency_key.
Payload size is capped by the project’s configured event payload limit.
Processing retries use exponential backoff before a dead-letter handoff.
Ordering across separate events is not guaranteed.

Retention

Default event retention is 90 days.
Retention windows can be adjusted through backoffice-managed project automation settings.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

event

string

required

Example:

"order.completed"

contact_id

string<uuid>

string<email>

external_id

string

payload

object

correlation

object

Show child attributes

contact

object

Show child attributes

occurred_at

string<date-time>

idempotency_key

string

Response

Event replay deduplicated

data

object

Show child attributes

Push Delivery Diagnostics List Templates

API Documentation

Emails

Project

Domains

Campaigns

Push Notifications

Events

Templates

Automations

Topics

Audiences

Audience Properties

Contacts

Endpoint

Request body

Successful response

Idempotent replay response

Reserved namespace

Guarantees and limits

Retention

Authorizations

Body

Response

​Endpoint

​Request body

​Successful response

​Idempotent replay response

​Reserved namespace

​Guarantees and limits

​Retention

Authorizations

Body

Response

Endpoint

Request body

Successful response

Idempotent replay response

Reserved namespace

Guarantees and limits

Retention