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_type": "contact_id",
"resolved_identity_value": "<string>",
"occurred_at": "2023-11-07T05:31:56Z"
}
}{
"status": 123,
"error": {
"code": "<string>",
"message": "<string>",
"details": "<string>",
"issues": [
{
"code": "<string>",
"path": "<string>",
"message": "<string>"
}
]
}
}{
"status": 123,
"error": {
"code": "<string>",
"message": "<string>",
"details": "<string>",
"issues": [
{
"code": "<string>",
"path": "<string>",
"message": "<string>"
}
]
}
}Events
Event Ingest
Submit customer events and understand reserved system event rules.
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_type": "contact_id",
"resolved_identity_value": "<string>",
"occurred_at": "2023-11-07T05:31:56Z"
}
}{
"status": 123,
"error": {
"code": "<string>",
"message": "<string>",
"details": "<string>",
"issues": [
{
"code": "<string>",
"path": "<string>",
"message": "<string>"
}
]
}
}{
"status": 123,
"error": {
"code": "<string>",
"message": "<string>",
"details": "<string>",
"issues": [
{
"code": "<string>",
"path": "<string>",
"message": "<string>"
}
]
}
}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"
}
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"
}
}
}
contact.mode: "upsert", event ingestion resolves existing contacts only.
Identity resolution order is:
contact_idexternal_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"
}
}
202 Accepted.
Idempotent replay response
If you reuse the sameidempotency_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 withsendrealm..
Examples of Sendrealm system events:
sendrealm.mail.deliverysendrealm.push.opensendrealm.contact.updatedsendrealm.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
Integration key for backend workloads, or a scoped personal key (sr_user_) for account discovery and supported project operations. MCP accepts only personal keys.
Headers
Explicit project context. Required for personal-key project resource calls; integration keys retain their configured default. MCP clients supply project_id in each tool call instead.
Body
application/json
Example:
"order.completed"
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Personal-key mutations default to suppress. Explicit trigger can start/resume live automations and deliver real messages; requires automations.trigger plus current management capability. Integration calls retain existing trigger default.
Available options:
suppress, trigger Response
Event replay deduplicated
Show child attributes
Show child attributes