Events API

Event Ingestion

Events are the foundation of Synapse. Every email flow starts with an event from your application. When a user signs up, makes a purchase, or completes an action, send an event to Synapse. The platform evaluates the event against active flows and triggers automated email sequences.

POST /v1/events

Ingest a single event. Requires an API key with data or full scope. Returns 202 Accepted on success.

Request body

Field	Type	Required	Description
`external_id`	string	Yes	Your application's user identifier (max 255 chars)
`event_name`	string	Yes	Event type identifier, e.g. `order_completed` (max 255 chars)
`attributes`	object	No	Arbitrary key-value data attached to the event
`contact`	object	No	Contact fields to upsert: `email`, `phone`, `first_name`, `last_name`, `timezone`
`idempotency_key`	string	No	Prevents duplicate processing (max 255 chars, 7-day TTL)
`occurred_at`	ISO 8601	No	When the event occurred (defaults to server time)

Example request

curl -X POST https://synapse-api.pyrx.tech/v1/events \
  -H "X-WORKSPACE-ID: ws_abc123" \
  -H "X-API-KEY: psk_live_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "user_12345",
    "event_name": "order_completed",
    "attributes": {
      "order_id": "ORD-2026-0042",
      "amount": 149.99,
      "currency": "USD",
      "items": ["Widget Pro", "Widget Lite"]
    },
    "contact": {
      "email": "[email protected]",
      "first_name": "Jane"
    },
    "idempotency_key": "order_completed_ORD-2026-0042"
  }'

Response (202 Accepted)

{
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "accepted"
}

POST /v1/events/batch

Ingest up to 50 events in a single request. Each event is processed independently — one failure does not block others. Ideal for SDK integrations and batch syncs.

curl -X POST https://synapse-api.pyrx.tech/v1/events/batch \
  -H "X-WORKSPACE-ID: ws_abc123" \
  -H "X-API-KEY: psk_live_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "external_id": "user_001",
        "event_name": "page_viewed",
        "attributes": { "page": "/pricing" }
      },
      {
        "external_id": "user_002",
        "event_name": "user_signed_up",
        "contact": { "email": "[email protected]" }
      }
    ]
  }'

Response (202 Accepted)

{
  "accepted": 2,
  "rejected": 0
}

Dashboard event endpoints

These endpoints use JWT authentication (dashboard sessions) rather than API keys.

Method	Endpoint	Description
`GET`	`/v1/events/list`	List events with cursor-based pagination, filtering by name, source, contact, and date range
`GET`	`/v1/events/{event_id}`	Get full event detail with associated contact info
`POST`	`/v1/events/trigger`	Trigger a new event from the dashboard for an existing contact
`POST`	`/v1/events/{event_id}/retrigger`	Re-trigger an existing event (test environment only)
`GET`	`/v1/events/attribute-keys`	Discover attribute keys for an event type (sampled from recent events)
`GET`	`/v1/events/attribute-values`	Get distinct values for a specific attribute key

Test vs. Live environments

The environment is determined by your API key prefix. Test keys (psk_test_) write to the test environment; live keys (psk_live_) write to the live environment. Data is completely isolated between environments.

Behavior	Test	Live
Contact data	Separate test contacts	Real contacts
Flow triggers	Only test contacts trigger flows	All contacts trigger flows
Email sending	Via sandbox sender (@test.pyrx.tech), daily cap	Via your verified domain, plan limits apply
Re-trigger	Allowed (POST /v1/events/{id}/retrigger)	Not allowed

Event naming best practices

•Use snake_case for event names: order_completed, user_signed_up
•Use past tense to describe what happened: invoice_paid not pay_invoice
•Keep attribute keys flat and descriptive: order_total not o.t
•Include the contact object on the first event for a user so the contact record is created with email and name
•Use idempotency_key for events that could be sent multiple times (e.g., webhook retries)

Error responses

Status	Code	Cause
401	Invalid or missing API key	Check X-WORKSPACE-ID and X-API-KEY headers
403	`plan_limit_reached`	Monthly event quota exceeded for your plan
403	Scope mismatch	API key requires `data` or `full` scope
422	Validation error	Missing required fields or invalid format

Deep dives

Event Ingestion

POST /v1/events endpoint: request schema, response format, error handling, and code examples.

Event Schema

Event attributes, contact overrides, naming conventions, timestamp handling, and attribute discovery endpoints.

Idempotency

Prevent duplicate processing with idempotency keys. Key format, TTL, and concurrent event handling.