Emails

POST /v1/emails sends a one-off transactional email. It resolves a recipient, renders a named template from your registry, and dispatches through the engine-owned tracked mailer — so link-click tracking, open tracking, and unsubscribe handling all apply automatically, exactly as they do for journey sends.

Requires a bearer key with the ingest scope.

Request

One of to or userId is required.

{
  "to": "ada@example.com",
  "userId": "user_123",
  "template": "welcome",
  "props": { "firstName": "Ada" },
  "from": "team@example.com",
  "subject": "Welcome aboard",
  "replyTo": "support@example.com",
  "category": "onboarding",
  "skipPreferenceCheck": false,
  "idempotencyKey": "email_welcome_user_123"
}

Recipient resolution

If you pass userId instead of to, the mailer resolves the recipient email from the contact record. If that contact has no resolvable email, the call returns 404.

skipPreferenceCheck is gated to full-admin

By default the send respects the recipient's subscription and suppression state — an unsubscribed or suppressed recipient is not emailed. skipPreferenceCheck: true bypasses that, and it is a privileged operation: the data-plane ingest scope is not enough. The key must hold full-admin, or the request returns 403.

Response 202

{ "emailSendId": "550e8400-e29b-41d4-a716-446655440000", "status": "queued" }

A suppressed or unsubscribed status means the recipient was on the suppression list or had opted out — the send was correctly withheld (a successful no-op, not an error).

Tracking and unsubscribe are inherited

Because /v1/emails flows through the same tracked mailer as every journey send, there is no extra wiring to get tracking:

• Links in the rendered HTML are rewritten to /v1/t/c/:id, so clicks are recorded and re-ingested as email.link_clicked events.
• An open pixel (/v1/t/o/:id) is injected, so opens are recorded and re-ingested as email.opened events.
• Unsubscribe headers (List-Unsubscribe, one-click) and the preference center links are added; those links are deliberately not rewritten for click tracking.

Opens and clicks loop back into the engine as first-class events — they can trigger journeys and move bucket membership. See the tracking reference for the collection endpoints.

Errors

Example

curl -X POST http://localhost:3002/v1/emails \
  -H "Authorization: Bearer $HOGSEND_DATA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "ada@example.com",
    "template": "welcome",
    "props": { "firstName": "Ada" }
  }'

{ "emailSendId": "…", "status": "queued" }