Inbox & Tickets

Read your team inboxes and their tickets, reply to customers, and move tickets through their workflow. Reading requires tickets:read; replying and changing status require tickets:write.

Endpoints, parameters and payloads

Exact paths, query parameters and request/response schemas live in the auto-generated API Reference — see Inboxes and Tickets. This page covers the behaviours the raw schema can’t.

A tenant-scoped API key sees all of your team inboxes and tickets — there’s no per-user inbox membership behind a key.

Ticket shape and enums

• status is open / snoozed / done / spam; priority is low / medium / high.
• reference and sequentialNumber are null until a ticket is assigned an inbox with a prefix.
• GET /v1/tickets/{id} returns the ticket, a summary of its contact, and the full message thread (oldest first). Internal notes are never included. contact may be null for anonymous tickets.
• On each message, type is reply, form_response or form_response_update; direction is inbound (from the customer) or outbound (from your team / the API).

Replying to a ticket

POST /v1/tickets/{id}/replies — html is required; text is an optional plain-text fallback. On success you get 201 Created with { "delivered": true, "messageId": "...", "channel": "email" }.

This sends a real email

A successful reply sends a real email to the customer on the ticket. The reply is attributed to your API key’s name (not a fake user). There is no draft/preview step — post it only when you mean to send it.

Replies are email-only in v1. Expect these failures:

Status	error	When
422	unprocessable	The ticket is on a live-messaging channel (chat/WhatsApp/etc.), or its contact has no email address.
502	delivery_failed	The email couldn’t be delivered, or the account hit its outbound daily limit. Not caused by your request.
404	not_found	No such ticket.

Changing ticket status

PUT /v1/tickets/{id}/status — status must be open, done, snoozed, or spam. When snoozing, snoozedUntil (an ISO-8601 timestamp) is required. A status change fires any subscribed ticket.status_changed webhook.

• 400 invalid_request — status isn’t one of the four values, or snoozedUntil is missing for snoozed.
• 404 not_found — no such ticket.