Send an email
POST/v1/emails
Accepts an email for delivery and returns immediately. Delivery is asynchronous: the response confirms that the message was accepted, priced and queued, not that it reached the recipient. Subscribe to webhooks or poll GET /v1/emails/{id} for the outcome.
Funds are reserved at the published price on acceptance and settled when the message goes out, so a message that is never sent is never charged for.
Parameters
| Name | In | Description |
|---|---|---|
| Idempotency-Keyrequired | header | A unique value per logical request, honoured for 24 hours. Required on
endpoints that spend money. Reusing a key with a different body returns
idempotency_conflict. |
| Woyra-Version | header | The dated API version to serve. Omit to pin to the oldest supported version. |
Body
| Field | Type | Description |
|---|---|---|
| in_reply_to | string | Makes this a reply. The id of an email received on this account
(inb_...) or sent from it (email_...). A reply to a received
email goes to its sender from the address it reached; a reply to
a sent email goes to the same recipient from the same sender;
the subject gains one Re:. The mail carries In-Reply-To and
References, so the recipient's client keeps it in the same
conversation, and it joins the thread here. |
| to | AddressList | One email address, or a list of them. |
| cc | AddressList | One email address, or a list of them. |
| bcc | AddressList | One email address, or a list of them. |
| reply_to | AddressList | One email address, or a list of them. |
| headers | object | Extra headers written into the email, such as List-Unsubscribe
for a newsletter or X-Entity-Ref-ID for your own reference.
Headers Woyra writes itself (From, To, Cc, Bcc, Reply-To, Subject,
Date, Content-*, MIME-Version, DKIM-Signature, Return-Path) and
any X-Woyra- header are refused, as are names or values with a
line break.
To keep your own conversations threaded, as a support desk does,
you may set In-Reply-To and References (message ids in angle
brackets, such as <id@yourapp.com>), and Message-ID. The mail
carries your In-Reply-To and References; your Message-ID goes into
References, because the sending network replaces the Message-ID
header itself. A reply to the mail therefore still names your id. |
| template_id | string | Send a saved template: its subject and bodies, with each
{{placeholder}} filled from variables. Values are HTML-escaped
in the HTML body. A subject given here replaces the template's.
A placeholder with no value refuses the send, naming it
(param is variables.<name>). |
| variables | object | |
| track_opens | boolean | Write an invisible image into the HTML body, so opens are
recorded (email.opened). A signal, not proof: some mail apps
load every image. |
| track_clicks | boolean | Route every web link in the HTML body through Woyra, so clicks
are recorded (email.clicked) on their way to the same address. |
| scheduled_at | timestamp | Send later: the email is accepted, priced and held with status
scheduled until this time, at most 30 days ahead. Cancel it
until then with POST /v1/emails/{id}/cancel, which gives back
everything accepting it took. |
| from | string | address or Name <address>.
Must be on a domain this account has verified, except in test mode.
Sending from an unverified domain would burn the shared sending
reputation every customer depends on. |
| subject | string | |
| text | string | Plain-text body. At least one of text or html is required. |
| html | string | HTML body. Supplying both produces a multipart/alternative message. |
| priority | string | Selects the dispatch queue. OTP traffic never queues behind a bulk
send, whatever the order in which they were accepted. One of otp, transactional, bulk. |
| routing | RoutingOptions | How Woyra should choose a route for this message. |
| webhook_url | string | An HTTPS endpoint to notify. Must resolve to a public address: private and link-local targets are rejected. |
| metadata | object | Arbitrary key/value pairs echoed back on the email and its webhooks. |
| test_mode | boolean | Console sessions only: send without spending, delivering nothing, exactly as a test key does. Ignored for API keys — a key's mode is a property of the key, and letting its holder override it would make a test key a live one. |
| attachments | array of OutboundAttachment | Files to send with the email. At most 20, and 10 MB of content in total once decoded — a receipt or an invoice, not a video. A larger file belongs behind a link, which arrives reliably where a large attachment may be refused several hops away. |
Example
curl -X POST https://api.woyra.io/v1/emails \
-H "Authorization: Bearer $WOYRA_KEY" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: send-email-1' \
-d '{
"to": "alex@example.com",
"from": "noreply@yourdomain.com",
"subject": "Your code",
"text": "Your code is 483920"
}'Response
200 Recorded but not sent, because the recipient is on this account's
| Field | Type | Description |
|---|---|---|
| objectrequired | "email" | |
| idrequired | string | |
| statusrequired | string | One of accepted, scheduled, queued, sent, delivered, undelivered, failed, suppressed, canceled. |
| torequired | string | The one address this copy went to. |
| fromrequired | string | |
| subjectrequired | string | |
| created_atrequired | timestamp | |
| scheduled_at | timestamp | When a scheduled email leaves. Absent once it has. |
| recipients | array of object | On the answer to a send with more than one recipient: one copy per person, each its own email with its own id, status and webhooks. The first is this email. |
| recipients.to | string | |
| recipients.id | string | |
| recipients.status | string | |
| events | array of EmailEvent | On GET /v1/emails/{id}: every status the email has had, oldest
first, so a support ticket can be answered from one request. |
| metadata | object | |
| thread_id | string | The conversation this email belongs to, readable at /v1/emails/threads/{thread_id}. |
| in_reply_to | string | The email this one answers, when it was sent as a reply. |
| route | RouteDecision | Which carrier carried this message, why it was chosen, and what it cost. No other provider shows this. |
| error | ErrorSummary | The canonical failure reason, normalised across every carrier. |
Errors
Also in Emails
- GET /v1/emails — List emails
- GET /v1/emails/{id} — Retrieve an email
- POST /v1/emails/{id}/cancel — Cancel a scheduled email
- POST /v1/emails/batch — Send a batch of emails
- GET /v1/templates — List templates
- POST /v1/templates — Save an email template
- GET /v1/templates/{id} — Retrieve a template
- PATCH /v1/templates/{id} — Change a template
- DELETE /v1/templates/{id} — Delete a template
- GET /t/o/{token} — Open tracking image
- GET /t/c/{token} — Click tracking redirect
- GET /v1/emails/inbound — Mail received on your domains
- GET /v1/emails/inbound/{id} — Retrieve a received email
- GET /v1/emails/inbound/{id}/attachments/{attachment_id} — Download an attachment
- GET /v1/emails/threads/{id} — A conversation