Send an email

Sends one message to up to 50 recipients, from a template or inline.

Wakio sends inline html and text as you give them, apart from filling in merge tags from merge_data: it adds no footer, no tracking and no unsubscribe link.

Replace YOUR_EMAIL_ADDRESS with your own address before you run the example. Wakio refuses the placeholder, so a pasted example never sends to it. Leave out from and the message goes from no-reply@ one of your sendable domains. With more than one, pass from to choose.

POST /v1/emails

Example

curl https://api.wakio.net/v1/emails \
  -H "Authorization: Bearer $WAKIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "YOUR_EMAIL_ADDRESS",
  "subject": "Hello from Wakio",
  "html": "<p>It works.</p>"
}'

Response 202:

{
  "id": 272531,
  "status": "queued"
}

Parameters

Name	Type	Required	Description
`to`	string or array of strings	No	Addresses such as `[email protected]` or `Maya Lee <[email protected]>`; quote a name that contains a comma. The name shows in the recipient's To line, and duplicates, suppressions and the response match on the address alone. `to`, `cc` and `bcc` together need at least one address and at most 50 once duplicates collapse, ignoring case. Naming more than 200 addresses is refused before duplicates collapse.
`cc`	string or array of strings	No	Copied recipients, counted with `to`.
`bcc`	string or array of strings	No	Blind-copied recipients, counted with `to`.
`template`	string	No	The key of a published template, set up with Wakio. Send either `template` or an inline message (`subject` plus `html` or `text`), never both.
`merge_data`	object	No	Values for `{{placeholders}}` in the template or the inline message. A placeholder with no value is sent as written. Values are HTML-escaped where they land in the HTML part, so send plain text, not markup. Each value must be a string, number, boolean or null, or the request answers 422. At most 256 KB as JSON.
`subject`	string	No	Inline subject. Required for an inline message. At most 998 bytes, no line breaks or control characters.
`html`	string	No	Inline HTML body. At most 512 KB.
`text`	string	No	Inline plain-text body. At most 256 KB.
`from`	string	No	A bare address or `Name <address>` on one of your sendable domains. Omitted, mail goes from `no-reply@` one of your sendable domains; with more than one, pass `from` to choose.
`reply_to`	array of strings	No	Up to 10 bare addresses.
`attachments`	array of objects	No	Each `{ "filename", "content_type", "content" }`, with `content` base64-encoded and `content_type` a bare MIME type such as `application/pdf`. Up to 20 files, filenames up to 255 bytes, 10 MB decoded and 15 MB encoded per request, and the decoded size times the number of recipients at most 50 MB.
`Idempotency-Key`	header	No	Any string up to 255 bytes. A blank key is treated as no key. Once a request with this key is accepted, a retry with a byte-identical body gets the first response back instead of sending again, for 24 hours. In that time the same key with any other body, even the same JSON with its keys reordered, is refused. A request refused before anything was accepted frees its key.

Response

Name	Type	Required	Description
`id`	integer	No	The delivery's id. Returned when the request names exactly one recipient.
`status`	string	No	Returned with `id`. A `status` of `suppressed` means Wakio did not send to that address.
`deliveries`	array	No	One `{ "email", "id", "status" }` per recipient. Returned when the request names more than one. A `status` of `suppressed` means Wakio did not send to that address.

Errors

Every error this endpoint itself returns is {"error": "<code>"}, sometimes with one more field that explains it. The API overview lists the responses that do not follow that shape.

Status	Code	What happened	What to do
`401`	`invalid_api_key`	The `Authorization` header is missing, malformed, or names no active key.	Send `Authorization: Bearer <key>` with an active key from API keys in the dashboard.
`402`	`not_entitled`	The account has no active plan. `reason` says why.	Choose a plan under Billing.
`403`	`account_suspended`	The account is suspended. `detail` gives the reason.	Email [email protected].
`409`	`request_in_flight`	A retry with the same `Idempotency-Key` and the same body arrives while the first request is still being processed, or after it failed with some recipients already accepted. In that case the key stays in flight for 24 hours.	Wait and retry with the same key. If it still answers 409, check Deliveries for what went out before sending the rest under a new key.
`422`	`invalid_request`	A field is missing, malformed or over its limit. `detail` names it.	Fix the field `detail` names.
`422`	`unknown_template`	No published template has that key. `template` echoes it.	Check the key. Templates are set up with Wakio for now; email [email protected].
`422`	`no_verified_sending_domain`	The account has no domain it can send from, or `from` is not on one.	Finish verifying a domain under Sending domains.
`422`	`idempotency_key_reused`	This `Idempotency-Key` was already used with a different body.	Use a new key for a different message.

Send from a template

Use a template's key instead of an inline message, and merge_data fills its placeholders. Templates are not managed in the dashboard yet. To have one set up, email [email protected].

curl https://api.wakio.net/v1/emails \
  -H "Authorization: Bearer $WAKIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "YOUR_EMAIL_ADDRESS",
  "template": "welcome",
  "merge_data": {
    "first_name": "Maya"
  }
}'

Notes

Send an Idempotency-Key when a duplicate would be worse than a missing send. A retry gets the first response back only if it sends the byte-identical body, for 24 hours.

A suppressed address is accepted, not refused, and its status says so. A request for one recipient answers with its id and status. A request for several answers with deliveries, one entry per address. A status of suppressed means Wakio did not send to that address.

Using Rails? The Rails guide sends through Action Mailer without calling this endpoint yourself. On WordPress, the WordPress plugin does the same for every email your site sends.