Send Custom Event

Send a custom event into OpenSend. This page documents the OpenSend-owned API contract for POST /events/send.

POST /events/send

Legacy OpenSend callers may continue to use POST /api/events/send with the same request and response shape.

Authentication

Use an OpenSend API key in the Authorization header. Dashboard session cookies are not API credentials for public API clients.

http

Authorization: Bearer os_YOUR_API_KEY

When to use it

Use this route to deliver a custom event for exactly one contact. Provide either contact_id/contactId or email, plus an optional payload object. If the event has a stored schema, OpenSend validates payload before recording the delivery or resuming automations.

Parameters

JSON body fields are validated before any database write. The route accepts:

event — custom event name.
contact_id or contactId — contact ID to associate with the event.
email — contact email to resolve instead of a contact ID.
payload — optional object passed to automations and schema validation.

properties is not accepted for event delivery data; use payload.

Request example

json

{
  "event": "user.signed_up",
  "email": "ada@example.com",
  "payload": { "plan": "pro" }
}

Response

Successful responses return 202 Accepted with the event delivery and any automation runs created or resumed:

json

{
  "object": "event_delivery",
  "delivery": {
    "object": "event_delivery",
    "id": "2d66f2de-0d0e-4a2d-8e66-831e3522d124",
    "event": "user.signed_up",
    "contact_id": "520784e2-887d-4c25-b53c-4ad46ad38100",
    "email": "ada@example.com",
    "payload": { "plan": "pro" },
    "received_at": "2026-06-08T00:00:00.000Z"
  },
  "resumed_runs": [],
  "automation_runs": []
}

Errors

OpenSend returns structured errors for missing authentication, invalid JSON, validation failures, schema mismatches, quota/rate-limit conditions, and unexpected server failures.

Self-hosting notes

Self-hosted deployments can use the same path on their own OPENSEND_BASE_URL. Run migrations before deploying code that expects new fields, and keep API keys in a secrets manager instead of committing them to source control.