API overview

The Wakio API sends transactional email, adds contacts, and reports which of your domains can send. Every request goes to https://api.wakio.net over HTTPS, sends and receives JSON, and carries an API key.

Send your first email

1. Issue a key under API keys in the dashboard and copy it. Wakio shows it once.
2. Set it in your shell: export WAKIO_API_KEY=wk_...
3. Run the request below.

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>"
}'

Replace YOUR_EMAIL_ADDRESS with your own address first. Wakio refuses the placeholder. A request that works answers 202:

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

The id is the delivery's id. Deliveries in the dashboard shows what happened to it. The Send an email reference lists every field.

Authentication

Send your key in an Authorization header on every request: Authorization: Bearer <key>. Keys start with wk_. Wakio shows a key once, when you issue it, so store it where your application reads its secrets. Revoke a key under API keys and it stops working at once.

1. Your new key. Wakio shows it once, so copy it somewhere safe now.

A missing, malformed or revoked key answers 401:

{
  "error": "invalid_api_key"
}

Errors

An error is a JSON body with an error code, and at most one explaining field: reason, detail, template or external_id. The status says what kind of failure it is, and the error code is stable, so branch on it rather than on the wording of detail.

Three responses do not follow that shape. A body that is not valid JSON gets a 400, and a path under /v1 that is not one of the endpoints listed here gets a 404; both come before Wakio reads the request. An unexpected failure on Wakio's side is a 500.

Retry a 500 with the same Idempotency-Key. If part of the request was already accepted, that retry answers 409 request_in_flight for up to 24 hours. Wakio keeps the key on purpose, so a retry cannot mail anyone twice. Deliveries shows what went out before you send the rest under a new key.

Each endpoint lists its own errors:

• POST /v1/emails
• POST /v1/contacts
• GET /v1/sending-identities
• GET /v1/ping

Limits

Wakio publishes no request rate limit for the API.

Each email request has these caps:

• Recipients: at most 50 across to, cc and bcc, once duplicates collapse.
• Addresses named: at most 200 across to, cc and bcc, counted before duplicates collapse.
• Body: at most 512 KB of html and 256 KB of text.
• Attachments: at most 20 files, 10 MB decoded in total.

A request over a cap answers 422 invalid_request, and detail names the cap.

Sending needs an active plan. An account without one gets 402 not_entitled, and reason says why. Transactional sends count toward your monthly allowance, but an account over its allowance can still send transactional email through the API.

Endpoints

• POST /v1/emails: Sends one message to up to 50 recipients, from a template or inline.
• POST /v1/contacts: Adds a contact, or finds the one that already has this email, and records their consent when you say they gave it.
• GET /v1/sending-identities: Lists your sending domains and whether each can send right now.
• GET /v1/ping: Checks that a key works and tells you which account it belongs to.
• Rails: send your Rails app's mail through Action Mailer.
• WordPress: send every email your WordPress site produces.