Transactional e-mails

A transactional e-mail goes to one person because of what they have just done. It needs no list and no marketing consent, and it is logged and followed like a campaign. See Overview.

With a template

The cleanest way: the content lives in Lekalao, the application sends only the data. Create a template named order-confirmation (Transactional templates), then:

curl -X POST https://api.lekalao.com/v1/transactional-mails/send \
  -H "Authorization: Bearer $LEKALAO_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Idempotency-Key: order-2026-00481-confirmation" \
  -d '{
    "template": "order-confirmation",
    "to": ["ada@example.com"],
    "locale": "en",
    "variables": {
      "customer": { "name": "Ada" },
      "order": {
        "number": "2026-00481",
        "total": "12,500 FCFA",
        "items": ["Wholemeal bread", "Croissant x4"]
      }
    }
  }'

In the template:

<p>Hello {{ customer.name }},</p>
<p>Your order <strong>{{ order.number }}</strong> is confirmed.</p>
<ul>
    {% for item in order.items %}
    <li>{{ item }}</li>
    {% endfor %}
</ul>
<p>Total: {{ order.total }}</p>

Variables are escaped; loops run over lists of plain values. The whole syntax is in Personalisation.

Without a template

Send the HTML as it is:

curl -X POST https://api.lekalao.com/v1/transactional-mails/send \
  -H "Authorization: Bearer $LEKALAO_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "to": ["ada@example.com"],
    "subject": "Your September invoice",
    "html": "<p>Hello Ada, your invoice is attached.</p>",
    "from_email": "invoices@mybakery.example",
    "from_name": "The Bakery",
    "attachments": [
      { "name": "invoice-2026-09.pdf", "content": "JVBERi0xLjcKJcfsj6IK…", "mime": "application/pdf" }
    ]
  }'

The fields

Field
`template`	The name of a transactional template.
`html`	The body, when there is no template. One of the two is required.
`subject`	The subject. With a template, it replaces the template’s own.
`to`, `cc`, `bcc`	Arrays of addresses, 50 at most together. Without `to`, the template’s default recipients.
`variables`	A free object, which fills the template.
`locale`	Which language version of the template to send. See below.
`from_email`, `from_name`, `reply_to`	The sender; otherwise the template’s, otherwise the team’s.
`mailer`	The name of one of the team’s sending providers, or of one the service provides, to force the route. Another team’s name is refused.
`attachments`	10 at most: `name`, `content` in base64, `mime` optional.

Every address counts against the month’s allowance, copies included: an e-mail to one person in to and two in cc counts three. A transactional e-mail is written to someone, not broadcast: more than 50 addresses answer 422 too_many_recipients.

In several languages

A template can have one version per language (Languages). locale picks it:

`locale` sent	Version used
absent	The base version.
`pt-BR`, and the template has `pt-BR`	`pt-BR`.
`pt-BR`, the template only has `pt`	`pt`.
`pt`, the template only has `pt-BR`	The base version: a language never takes a regional version.
a language with no version	The base version.

Pass your customer’s language as your application knows it: Lekalao falls back on its own.

The answer

The call is answered as soon as the e-mail is written down. It leaves from a queue a moment later.

Code	`status`	`code`	When
`202`	`pending`		The usual answer: the e-mail is logged and waits its turn on the queue.
`201`	`sent`		The e-mail had already been handed to the provider when the answer left.
`422`	`failed`	`recipients_suppressed`	Logged, not sent: every address in `to` is on the suppression list.
`429`	`failed`	`monthly_quota_exceeded`	Logged, not sent: the plan’s e-mails of the month are used up.
`422`	`failed`	`sending_paused`	Logged, not sent: the team’s paid period ended without a payment.
`502`	`failed`	`queue_unavailable`, `provider_error`	Logged, not sent: the queue could not take it, or the provider refused it. With the queue running apart, as on Lekalao’s service, the provider’s refusals come later, on the queue; with a test key, `failed@sink.lekalao.dev` answers it at once.
`422`	—	`validation_error`, `content_missing`, `recipient_missing`, `too_many_recipients`, `sender_not_allowed`, `template_error`	Nothing is logged: a field is invalid (an unknown `template`, say), neither `template` nor `html` is given, there is no recipient at all, more than 50, or the sender is not allowed.

A refusal is an error like any other — message, code, doc_url — with the logged e-mail under data when there is one:

429 Too Many Requests

{
    "message": "Your plan sends 10000 e-mails a month, and they are used up.",
    "code": "monthly_quota_exceeded",
    "doc_url": "https://docs.lekalao.com/errors#monthly_quota_exceeded",
    "data": { "id": "e3b0c442-98fc-4c14-9a1e-2f6b7d8a9c10", "status": "failed", "failure_code": "monthly_quota_exceeded", "…": "…" }
}

The e-mail itself:

202 Accepted

{
    "data": {
        "id": "e3b0c442-98fc-4c14-9a1e-2f6b7d8a9c10",
        "template": "order-confirmation",
        "subject": "Order 2026-00481 confirmed",
        "from": "hello@mybakery.example",
        "to": ["ada@example.com"],
        "cc": [],
        "bcc": [],
        "status": "pending",
        "sandbox": false,
        "failure_reason": null,
        "failure_code": null,
        "opens": 0,
        "clicks": 0,
        "sent_at": null,
        "delivered_at": null,
        "bounced_at": null,
        "complained_at": null,
        "created_at": "2026-09-17T10:14:02+00:00"
    }
}

Treat 201 and 202 the same way: Lekalao has the e-mail. Keep its id; status tells whether it has left yet. Addresses on the suppression list are left out of to, cc and bcc without an error. The e-mail goes to the others, and fails only when no to is left.

Then, on the queue

Lekalao hands the e-mail to the provider. When the provider fails (a timeout, an error, a refusal), Lekalao tries again after 5 seconds, then 30 seconds, 2 minutes, 10 minutes and 30 minutes. It gives up after the sixth failed attempt, and in any case six hours after the call. status then becomes failed, with failure_code: provider_error and the provider’s last error in failure_reason. An e-mail whose job was lost on the way — a worker stopped, a queue emptied — is not left pending for ever: seven hours after the call, it becomes failed with failure_code: lost. Its content may not have been kept, so it is not sent again behind your back: send it again yourself. Transactional e-mails have a queue of their own: they never wait behind a campaign. The mailer’s rate limit still applies.

`status`	Means	Final
`pending`	Queued, or waiting to be tried again.	No
`sent`	Handed to the provider. Not yet delivered: see below.	Yes
`failed`	Not sent, and given up. Why is in `failure_code` and `failure_reason`.	Yes

`failure_code`	Means
`recipients_suppressed`	Every address in `to` is on the suppression list.
`monthly_quota_exceeded`	The month’s allowance was used up.
`sending_paused`	The team’s paid period ended without a payment.
`provider_error`	The provider refused it on every try, for six hours.
`queue_unavailable`	The queue could not take it.
`lost`	Still `pending` seven hours after the call: its job was lost.

Follow it with webhooks

Rather than read the e-mail again and again, let Lekalao tell you. Subscribe an endpoint to the transactional.* events (Webhooks):

Event	When
`transactional.sent`	The provider took it.
`transactional.delivered`	The provider reports it delivered, for each address.
`transactional.bounced`	It bounced, hard or soft.
`transactional.complained`	A reader reported it as spam.
`transactional.opened`	The first open.
`transactional.clicked`	The first click on each link.
`transactional.failed`	It will not leave, whatever the reason: `failure_code` says which.

Each one carries the e-mail as the API shows it: store its id with your order, and match on it. sent means the provider has it, not that it arrived. delivered_at is set when the provider reports a delivery, bounced_at when the address bounced for good, complained_at when a reader reported it as spam; status stays sent, and after a bounce failure_reason takes the provider’s reason. The address goes on the suppression list after a hard bounce or a complaint: the next e-mail to it will not leave. The same news also reaches mail.bounced and mail.complaint, with transactional_mail set to the e-mail’s id.

Or read it again

Without an endpoint, read the e-mail with GET /v1/transactional-mails/{id} until status is no longer pending. The token needs Read, which a Read and write token has.

curl https://api.lekalao.com/v1/transactional-mails/e3b0c442-98fc-4c14-9a1e-2f6b7d8a9c10 \
  -H "Authorization: Bearer $LEKALAO_TOKEN" \
  -H "Accept: application/json"

Space the calls out. They count against the token’s limit (120 calls a minute by default), with everything else the token does:

// Node 18 or later. Run it from a background job, never while your customer waits.
async function followMail(id) {
  for (const seconds of [1, 2, 4, 8, 15, 30, 60]) {
    await new Promise((resolve) => setTimeout(resolve, seconds * 1000));

    const response = await fetch(`https://api.lekalao.com/v1/transactional-mails/${id}`, {
      headers: {
        Authorization: `Bearer ${process.env.LEKALAO_TOKEN}`,
        Accept: 'application/json',
      },
    });
    const { data } = await response.json();

    if (data.status !== 'pending') return data; // "sent" or "failed"
  }

  return null; // Still pending after two minutes: it may be retrying. Look again later.
}

When the call itself fails

A timeout or a 5xx leaves you not knowing whether Lekalao has the e-mail. Send the same call again with the same Idempotency-Key:

if Lekalao answered the first time, you get that first answer back, with Idempotent-Replay: true, and no second e-mail leaves. It is the answer as it was then, pending included: read the e-mail to know where it stands now. A 422 or a 429 is kept too: the same key gives the same refusal;
a 502 is not kept, so the same key sends again.

A key is kept 24 hours. See Idempotency.

Follow and send again

Call
`GET /transactional-mails?template=order-confirmation&status=failed&to=ada@example.com`	The log, filtered.
`GET /transactional-mails/{id}`	One e-mail, with its status, opens and clicks.
`GET /transactional-mails?sandbox=true`	Only the e-mails sent with a test key; `false`, only the real ones.
`POST /transactional-mails/{id}/resend`	Sends it again as a new e-mail, with the same answers as a send. `409` `mail_not_kept` when the template did not keep the content.

A resend takes the same recipients, variables, language, subject and sender address (from_email), and the same provider. It does not take the attachments, which are never kept, nor a from_name or reply_to given in the first call: the template’s, or the team’s, are used. A test e-mail sent again stays a test e-mail.

Without sending anything

A test key sends nothing: the e-mail is checked, rendered and logged, marked sent with "sandbox": true, and counted against nothing. Written to delivered@sink.lekalao.dev, bounced@sink.lekalao.dev and their siblings, it gets the provider’s answer and its webhooks, to try your handlers end to end.

Other roads

A Laravel application can keep Mail::to()->send(): see Laravel transport.
Software that only speaks SMTP: see SMTP relay.

The API

Recipes

Integrations

Transactional e-mails

With a template

Without a template

The fields

In several languages

The answer

Then, on the queue

Follow it with webhooks

Or read it again

When the call itself fails

Follow and send again

Without sending anything

Other roads

​With a template

​Without a template

​The fields

​In several languages

​The answer

​Then, on the queue

​Follow it with webhooks

​Or read it again

​When the call itself fails

​Follow and send again

​Without sending anything

​Other roads

With a template

Without a template

The fields

In several languages

The answer

Then, on the queue

Follow it with webhooks

Or read it again

When the call itself fails

Follow and send again

Without sending anything

Other roads