Sending email

POST /emails accepts one recipient per request. It requires emails:send:transactional or emails:send:marketing, Idempotency-Key, an authorized sender and product capacity.

Send inline content

This example is Transactional. Replace addresses with ones authorized in your environment:

curl "$SENDIRO_API_BASE/v1/workspaces/$SENDIRO_WORKSPACE_ID/emails" \
  -H "Authorization: Bearer $SENDIRO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-confirmation-unique-operation" \
  --data '{
    "purpose": "transactional",
    "from": {"email": "team@example.com", "name": "Team"},
    "recipient": {"kind": "address", "address": {"email": "customer@example.net"}},
    "content": {"kind": "inline", "subject": "Order received", "body": {"text": "We received your order."}}
  }'

You can use recipient: {kind: "contact", contactId: "CONTACT_ID"}. Transactional accepts an address without creating a profile or subscribing it to Marketing. A Marketing unsubscribe does not prevent Transactional; delivery suppression can.

Marketing requires purpose: "marketing" and an active, subscribed, unsuppressed contact recipient. Audience membership does not replace consent.

Use a publication

Instead of inline content, use an immutable published revision:

{
  "kind": "emailDesign",
  "emailDesign": {"emailDesignId": "DESIGN_ID", "revisionId": "REVISION_ID"},
  "variables": {"orderNumber": "A-123"}
}

This object replaces content. Do not combine inline subject or body with emailDesign. Variables must match the design’s declarations. Obtain IDs from an administrator: keys cannot list or publish designs.

Follow progress

A 202 returns a receipt with id, workspaceId, status: "queued" and acceptedAt. Read GET /emails/{id} with emails:read. GET /emails supports purpose, contact and submission status filters.

queued, sending and retry_scheduled describe pending work. submitted confirms transport acceptance; failed and suppressed are known final outcomes. submission_unknown retains uncertainty and its reservation: do not send again with another key.

The delivery property retains later delivery, bounce, complaint, open and click observations. Read GET /emails/{id}/events with both emails:read and events:read, or receive webhooks. Delivery does not guarantee inbox placement.