API · Events

Send Event

Send an event to trigger automations, even if the event has no saved definition (requires full access). Sent events are kept for 30 days and are not forwarded to webhooks.

POST/events/sendFull access

Request parameters

Parameter	Type	Description
`Idempotency-Key` header · optional	`string` 1–256 characters	Makes the request safe to retry. See Idempotency.
`event` body · required	`string`	The name of the event to send.
`contact_id` body · optional	`string \| null`	Existing contact ID, required unless email is supplied; an unknown ID returns 404.
`email` body · optional	`string \| null`	Contact email address, required unless contact_id is supplied; an unknown address creates a contact when an automation starts.
`payload` body · optional	`object \| null`	Event values up to 64 KiB and 32 nesting levels, with printable ASCII keys not starting with $; declared properties are required with matching types and ISO 8601 dates.

Request example

Set OPENSEND_BASE_URL=https://api.example.com and OPENSEND_API_KEY=os_replace_me on your server.

bash

curl -X POST "$OPENSEND_BASE_URL/events/send" \
  -H "Authorization: Bearer $OPENSEND_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"event":"user.signed_up","email":"ada@example.net","payload":{"plan":"starter"}}'

Response

202 · application/json. Example IDs stand for IDs returned by your installation.

json

{
  "object": "event",
  "event": "example"
}

Behavior and errors

An undefined event is accepted without creating a definition. Unknown email addresses become contacts only when an enabled automation starts a run. An unknown contact_id returns 404. Custom events are not delivered as webhooks. Use Idempotency-Key for retry safety.

Use a full-access credential. Resource IDs belong to your team; an unknown or foreign resource returns 404. See authentication, errors, rate limits, and compatibility for the shared contract.