REST API Reference

Retrieve one delivery by the id returned in a send response. Statuses are scheduled, queued, sent, delivered, opened, retrying, failed, bounced, or canceled, and are kept current by the delivery providers — no action needed on your side. scheduled means the delivery was created ahead of a future scheduled_at and has not been dispatched yet; retrying means a send attempt failed and another is scheduled, so failed always means final. A canceled delivery carries error_message with the reason (requested, recipient_deleted, no_live_channels, or channel_deleted_or_detached). A failed delivery carries friendly_error_message, and limit_feature_key when a plan limit caused the failure.

Retrieve several deliveries at once — the usual way to poll a whole send. Ids that do not resolve are simply absent from the response rather than an error, so one stale id never fails a poll.

List the account's webhook endpoints. An account has at most one, so this returns zero or one entry. The signing secret is never included here — only a preview of it.

Register the endpoint delivery events are POSTed to. Responds 201 with the endpoint including its plaintext secret — the only response that carries it besides rotate_secret, so store it now. Responds 409 when the account already has an endpoint (update or delete the existing one instead), and 422 when the URL is not https or resolves to a private, loopback, or otherwise non-public address.

Retrieve the endpoint: url, active, secret_preview, consecutive_failure_count, last_success_at, and auto_disabled with disabled_at / disabled_reason when RelayGrid switched it off.

Move the endpoint to a new URL, or pause dispatch without deleting it by setting active to false.

Stop sending events and release the account's endpoint slot, so a new one can be registered.

Issue a new signing secret and return it in full. The previous secret stops verifying immediately, so deploy the new one to your receiver first.

Re-enable an endpoint that was auto-disabled after 20 consecutive failed events, and reset its failure count. Events emitted while it was disabled are not replayed.

Queue a signed ping event, dispatched through the same signing and retry path as a real event. Responds 202 with the event_id; the result shows up in the attempt log, not in this response.

The 50 most recent dispatch attempts, newest first: event_id, event_type, attempt_number, succeeded, response_code, error_message, and duration_ms. Attempts are pruned after 30 days.

List all notification users for the account

Get the notification user record for the currently authenticated user

Get a notification user by ID, including their contacts (one per channel type)

Create a new notification user

Update an existing notification user

Delete a notification user

Get all messages for a specific notification user

List a recipient's contacts — the addresses deliveries are sent to, one per channel type. Sending with message[user][email] manages these for you.

Add a contact for one channel type

Update a contact.

Remove a contact. Deliveries on that channel will then fail with "no contact on file".

List every segment in the account, newest first. Each entry includes its name and rules but not a live recipient_count — that's a COUNT query per segment, so it's only computed on show and preview, where one query is one deliberate request.

Retrieve a segment, including a live recipient_count computed from its current rules. Responds 404 for an unknown or deleted segment.

Create a segment. Responds 201 with the segment. Responds 422 for a name already used by another live segment in the account, or for invalid rules — an unknown field, an unknown operator, an operator not allowed for that field, an invalid channel value, an unparseable created_at value, or a relative created_at offset paired with eq/neq.

Update a segment's name and/or rules. Responds 200 with the segment. Fails for the same reasons as create.

Soft-delete a segment, freeing its name for reuse. Does not affect a broadcast already in flight for it.

Count and sample the recipients a rules payload would match, without saving anything — what a rule-builder UI calls as the caller edits conditions. Responds 200 with { count, sample }, where sample is capped at 5 recipients and uses the same fields as the notification_users endpoints above. Responds 422 for the same invalid-rules reasons as create.

Broadcast a template to every recipient matched by a segment. Address the segment and the template by name or internal id. Responds 202 with { broadcast: {...} } (fields below) — recipient resolution and delivery happen in the background, so there are no message or delivery ids to report yet; poll GET /api/v1/broadcasts/:id until status moves from pending to finished (or limit_reached when the monthly allowance stopped it early) and created_message_count settles. The segment must have at least one condition — or its rules must carry "match_all": true — or the send returns 422 with "Segment has no rules; set match_all to broadcast to every recipient". A scheduled_at defers each fanned-out message individually; to undo a scheduled broadcast, cancel its messages one at a time with DELETE /api/v1/messages/:id/schedule — there is no broadcast-level bulk cancel (known limitation).

List the account's broadcasts, newest first.

Retrieve one broadcast, including its current status and created_message_count. Responds 404 for an unknown id or another account's broadcast.

List all message templates

Create a new message template

Retrieve details of a specific template

Update an existing message template

Delete a message template

List all categories for the account, ordered by name

Retrieve a single category by ID

Create a new category

Update an existing category

Delete a category

List all notification channels for the account

Retrieve a specific notification channel by ID

Create a new notification channel

Update an existing notification channel

Delete a notification channel

Send a test message using the channel's configuration

Generate a signed channel token for a notification user, valid for 1 hour

List all pending invitations

Invite a new user to the account

Resend/renew an invitation

Revoke an invitation

List all feature votes

Vote for a feature

Remove a vote

Get recent notification stats for templates

List all email layouts for the account

Create an email layout. Use mode "simple" for structured branding, or "custom" for a full HTML layout (which must contain exactly one {{content}} placeholder).

Retrieve a specific email layout

Update an email layout

Soft-delete an email layout. Channels referencing it fall back to the default (unbranded) email.

Render posted layout attributes against a sample body; returns { html, text }. Use to preview branding before saving.