AllyOneMail / Sending emails

Sending Emails

A single central endpoint for all transactional or marketing sending.

POST /api/v1/send

{
  "from": "hello@company.com",
  "to": "customer@destination.com",
  "subject": "Email subject",
  "html": "<p>HTML content</p>",
  "text": "Plain-text content (fallback)",
  "reply_to": "support@company.com",
  "attachments": [
    { "filename": "invoice.pdf", "content": "<base64>", "type": "application/pdf" }
  ],
  "tags": ["welcome"],
  "metadata": { "order_id": "1234" },
  "track_opens": true,
  "track_clicks": true,
  "test_mode": false
}

Field	Required	Notes
`from`, `to`, `subject`	Yes	`subject` up to 998 characters. `to` accepts a string or an array.
`html` / `text`	At least one	Send both when possible — `text` is the fallback for clients without HTML.
`attachments`	No	Content in base64.
`track_opens` / `track_clicks`	No	On by default.
`test_mode`	No	Validates the payload without actually delivering — useful in CI.

Idempotent sending

To avoid duplicates on a network retry, use POST /api/v2/messages — same schema as above, plus idempotency_key (up to 200 characters). The key is valid for 7 days:

Situation	Response
First call with the key	Normal send.
Same key and same content, send already completed	`200` with the original `message_id` and `"deduplicated": true` — nothing is resent.
Same key, first call still in progress	`202` `{"status": "processing"}` — check again shortly.
Same key with different content	`409` `IDEMPOTENCY_CONFLICT`.