WoyraDocs
Get an API key

Send an email

POST/v1/emails

Emails · Requires an API key

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

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 \
  -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

FieldTypeDescription
objectrequired"email"
idrequiredstring
statusrequiredstring
One of accepted, scheduled, queued, sent, delivered, undelivered, failed, suppressed, canceled.
torequiredstringThe one address this copy went to.
fromrequiredstring
subjectrequiredstring
created_atrequiredtimestamp
scheduled_attimestampWhen a scheduled email leaves. Absent once it has.
recipientsarray of objectOn 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.tostring
recipients.idstring
recipients.statusstring
eventsarray of EmailEventOn GET /v1/emails/{id}: every status the email has had, oldest first, so a support ticket can be answered from one request.
metadataobject
thread_idstringThe conversation this email belongs to, readable at /v1/emails/threads/{thread_id}.
in_reply_tostringThe email this one answers, when it was sent as a reply.
routeRouteDecisionWhich carrier carried this message, why it was chosen, and what it cost. No other provider shows this.
errorErrorSummaryThe canonical failure reason, normalised across every carrier.

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