WoyraDocs
Get an API key

Send a batch of emails

POST/v1/emails/batch

Emails · Requires an API key

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

NameInDescription
Idempotency-KeyrequiredheaderA 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-VersionheaderThe dated API version to serve. Omit to pin to the oldest supported version.

Body

FieldTypeDescription
in_reply_tostringMakes 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.
toAddressListOne email address, or a list of them.
ccAddressListOne email address, or a list of them.
bccAddressListOne email address, or a list of them.
reply_toAddressListOne email address, or a list of them.
headersobjectExtra 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_idstringSend 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>).
variablesobject
track_opensbooleanWrite an invisible image into the HTML body, so opens are recorded (email.opened). A signal, not proof: some mail apps load every image.
track_clicksbooleanRoute every web link in the HTML body through Woyra, so clicks are recorded (email.clicked) on their way to the same address.
scheduled_attimestampSend 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.
fromstringaddress 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.
subjectstring
textstringPlain-text body. At least one of text or html is required.
htmlstringHTML body. Supplying both produces a multipart/alternative message.
prioritystringSelects the dispatch queue. OTP traffic never queues behind a bulk send, whatever the order in which they were accepted.
One of otp, transactional, bulk.
routingRoutingOptionsHow Woyra should choose a route for this message.
webhook_urlstringAn HTTPS endpoint to notify. Must resolve to a public address: private and link-local targets are rejected.
metadataobjectArbitrary key/value pairs echoed back on the email and its webhooks.
test_modebooleanConsole 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.
attachmentsarray of OutboundAttachmentFiles 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.

FieldTypeDescription
objectrequired"list"
datarequiredarray of Email
has_morerequiredboolean
next_cursorstring

Errors

StatusCodes
400invalid_request, unsupported_version
401authentication_required, invalid_api_key
402insufficient_funds, spend_cap_exceeded, email_limit_reached
403insufficient_scope, domain_not_verified, recipient_suppressed, sending_paused, mfa_required
409idempotency_conflict, idempotency_in_progress
429rate_limited, daily_send_limit_reached

Also in Emails