Mail API

This article and the rest of the API documentation in this section are written for a technical audience — integrators and developers connecting external systems to Tickiti. Familiarity with HTTP, REST, JSON and bearer-token authentication is assumed.

The Mail API sends email and exposes the Mail admin screens — mailboxes, ignored subjects, excluded emails and the sent-mail audit. Every endpoint runs as the token’s owner and is gated by the mail ability plus the owner’s admin role.

Gmail OAuth connection and raw .eml download are browser flows, available from the Mail screens.

Abilities and conventions

1. mail:read — read endpoints.
2. mail:write — send, create / update / delete endpoints. Write implies read.

All endpoints are POST and JSON. Mailbox reads never include secrets (POP/SMTP passwords, OAuth refresh token) — only a gmail_connected flag. See the API overview for the shared request and authentication conventions, and Custom domain setup for the related sending-domain configuration.

Endpoints

Sending email

POST /api/v1/mail/send sends one email from one of your mailboxes. It is not tied to a ticket — use the Reply to ticket API to write to a customer on a ticket.

The request needs an Idempotency-Key header: resending the same request with the same key returns the stored result and sends nothing more, and the same key with a different body is refused with 409. See Idempotency.

Body fields:

1. to_address — required. The recipient.
2. Then exactly one payload shape: subject + content (HTML), or template_identifier + data — an email-type template rendered with the token values in data. With a template, a subject you send replaces the template’s subject.
3. cc — optional array of additional recipients; each must be a valid email address.
4. mailbox — optional. The name of the mailbox to send from. Omit it to send from the default mailbox.
5. validate_address — optional, default false. When true, a malformed to_address is refused with 422 straight away; otherwise the message is accepted and queued on its shape alone.

A template’s inline images are embedded in the message, so they display in the recipient’s mail client. To check a template’s output without sending it, use templates/render.

curl -X POST https://support.sole-trader.example/api/v1/mail/send \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Idempotency-Key: 3f9c1a52-6e0b-4d7a-8b21-9c4e5f6a7b8c" \
  -H "Content-Type: application/json" \
  -d '{
    "to_address": "[email protected]",
    "template_identifier": "order_dispatched",
    "data": { "name": "Marcus", "order_number": "TB-10442" }
  }'

Successful response:

{
  "ok": true,
  "data": {
    "mailbox": "[email protected]",
    "used_template": true
  }
}

A request with neither payload shape, an unknown mailbox or an unknown template is refused with 422 and an errors object naming the field.

Sent mail

1. sent-mail lists mail sent in the last range_days days (1–30, default 1), newest first. limit (1–300) caps the number of rows; up to 300 are returned. Each item carries id, sent_at, to_address, subject and can_download.
2. sent-mail/search takes q (also accepted as search), which matches the subject and the to_address, and limit (1–500, default 200). q is required: a call without it is refused with 422. An empty items list means nothing matched.
3. sent-mail/show takes an id and returns the message’s from, to, cc, bcc and reply-to addresses, subject and html, with inline images embedded so the HTML displays on its own.