Tickiti

Send email 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 send-email endpoint dispatches a single email through one of Tickiti’s outbound mailboxes. Unlike Create ticket API, no ticket is created — it is purely a transport.

Use it when the integration wants Tickiti’s mail infrastructure (the configured mailbox, deliverability, retention, sent-mail audit) without coupling to a ticket lifecycle. Common cases: order confirmations, invoice deliveries, shipping notifications.

Endpoint

POST /api/send_email

Headers

  1. Authorization: Bearer YOUR_TOKEN — required. Token must have the send-email ability.
  2. Idempotency-Key: <uuid> — required. Replays return the original response; conflicts on different payloads return 409.
  3. Content-Type: application/json — required.

Body

Required:

  1. to_address — the recipient email address.

Pick exactly one payload shape:

  1. A) Direct subject/content — subject and content (string, HTML allowed).
  2. B) Template render — template_identifier (must exist in Templates) and data (object with the placeholders the template expects).

Optional:

  1. mailbox — the name (not the address) of the mailbox to send from, as listed under Mail → Mailboxes. If omitted, Tickiti picks the mailbox whose address matches config('app.mail_from_address'); if no match, the first SMTP-enabled mailbox by creation order.
  2. validate_address — boolean, default false. When true, Tickiti validates to_address as a syntactically correct email address before sending. Set to true on caller-supplied addresses; leave false when the address comes from a controlled source.

Example A — direct content

curl -X POST https://support.sole-provider.example/api/send_email \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "to_address": "marcus@trailblazers-club.example",
    "subject": "Your order SP-2412-0489 has shipped",
    "content": "<p>Hi Marcus,</p><p>Tracking: TRACK-XYZ.</p>"
  }'

Example B — template

{
  "to_address": "marcus@trailblazers-club.example",
  "template_identifier": "invoice_delivery",
  "data": {
    "invoice_number": "INV-2026-0488",
    "amount": "£189.00",
    "due_date": "2026-05-15"
  }
}

Successful response

{
  "ok": true,
  "data": {
    "mailbox": "support@sole-trader.example",
    "used_template": false
  }
}

The response confirms which mailbox the message went out from and whether a template was used. There is no message-id or sent timestamp in the response — for those, look up the entry in the Mail → Sent mail audit.

Error responses

  1. 422 validation_failed — missing/invalid recipient or payload, template not found, mailbox does not exist.
  2. 409 idempotency_key_conflict — same key used with a different payload.
  3. 401 / 403 — bad token or missing send-email ability.

What gets logged

Every send_email call appears in the Mail → Sent mail audit with subject, recipient, sent-at timestamp and a copy of the rendered email body. Use the audit page to verify deliverability and retain proof of dispatch for your compliance needs.

When NOT to use send_email

If the email is the start of (or relates to) a customer conversation that should be tracked, file a ticket with Create ticket API instead. send_email is fire-and-forget; once it is sent, Tickiti does not track replies, threading, or follow-up — that is what tickets are for.