Send a batch of emails
POST/v1/emails/batch
Up to 100 emails in one request, each shaped like a POST /v1/emails body, reaching at most 1,000 recipients in all. All or nothing: every email is checked first, and a problem with any of them refuses the batch, naming it (param is [3].to). One idempotency key covers the batch.
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/batch \
-H "Authorization: Bearer $WOYRA_KEY" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: send-email-batch-1' \
-d '{
"in_reply_to": "<in_reply_to>",
"to": "+251911234567",
"cc": "<cc>"
}'Response
202 Every email accepted, in the order sent.
| Field | Type | Description |
|---|---|---|
| objectrequired | "list" | |
| datarequired | array of Email | |
| has_morerequired | boolean | |
| next_cursor | string |
Errors
Also in Emails
- GET /v1/emails — List emails
- POST /v1/emails — Send an email
- GET /v1/emails/{id} — Retrieve an email
- POST /v1/emails/{id}/cancel — Cancel a scheduled email
- 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