Send Events

post

https://api.pushly.com/domains/{domain_id}/events

Accepts a batch of up to 100 events for one domain. Events are processed asynchronously: a 202 means an event was stored and queued for matching against journeys, not that a notification was sent.

Once the request has been read, the HTTP status is 202 even when no event was accepted. Read the per-event status in data; an event with an error_message was not accepted.

Re-sending an event with the same event_name and event_id is safe and does not produce a second notification. Retry per-event 500s with the same event_id. Do not retry 400s or 413s unchanged.

Path Params

domain_id

integer

required

Domain ID

Body Params

events

array of objects

required

length between 1 and 100

The events to send. The whole body may be at most 1,048,576 bytes.

events*

event_id

string

required

length ≥ 1

Your unique ID for this event. Must stay the same every time the event is sent, including retries. An event is identified by event_name and event_id together.

event_name

string

required

length between 1 and 128

What happened. Journeys listen for events by this name. Template delimiters ({{, }}, {%, %}, -%}) and leading and trailing whitespace are removed before the 128-character limit is applied.

audience

required

Who the event concerns. Exactly one of external_ids, pushly_ids or broadcast: true. Declaring none or more than one fails the whole request with 400.

properties

object

Data about the event, for journey conditions and message content ({{event.properties.<path>}}). At most 51,200 bytes as compact JSON with non-ASCII characters escaped; a larger event is refused with a per-event 413. Property types are inferred and registered automatically. Template delimiters are removed from keys and string values. For a journey to target subscribers inside a geographic area, send the area as an object of the form {"points": [[longitude, latitude], ...]} with at least three points; GeoJSON is not accepted.

schema_version

integer

≥ 1

Defaults to 1

The version of this event's property layout. Increase it for a breaking change to the event's shape.

occurred_at

When the event happened. Defaults to the time Pushly received it.

ISO 8601. A value with no offset is read as UTC.

expires_at

When the event stops being worth a notification. An event that arrives already expired is accepted with a warning and not sent. Defaults to 24 hours after arrival unless Pushly has configured otherwise, and never later than the retention period (30 days by default).

ISO 8601. A value with no offset is read as UTC.

priority

string

enum

Defaults to medium

Requested processing priority. Lowered to the event type's ceiling, which is high unless Pushly has configured otherwise.

Allowed:

trace_id

string

Your identifier for this request, kept with every event in it. Generated when omitted. Not returned in the response.

202The request was read and each event has its own result. status is success if at least one event was accepted, error if none was.

400The request is malformed. Nothing in it was accepted. Do not retry unchanged.

401Request signing is set up for this domain and the X-Pushly-Signature header is missing, malformed, outside the five-minute window or does not match.

403The API key is not an API token, or has no access to this domain.

404The domain was not found.

500An unexpected error. It cannot be known which events were accepted: retry the whole request unchanged, with backoff. Events already accepted are recognized by event_id and not sent twice.