Skip to content
Facteur for developers

The Facteur API

Give every test suite its own inboxes. Send mail to them, and assert on what arrives — codes, links, headers — without writing a retry loop.
QuickstartAPI reference

What this API is for

Section titled “What this API is for”

Your application sends a confirmation email. Your test needs the code inside it. Without a mailbox it can read, that test either mocks the mail away — proving nothing about the thing most likely to break — or it polls a real one in a loop with a magic number in it.

Facteur is the mailbox it can read. Point your application’s SMTP at an inbox, then ask for the message:

Terminal window
curl -X POST https://api.facteur.eu/v1/messages/search \
  -H "Authorization: Bearer fk_your_key" \
  -H "content-type: application/json" \
  -d '{"inbox": "j3k9x2mq", "sentTo": "signup+7c1e", "wait": 30000}'

That request does not answer until the message is there and fully parsed, or until thirty seconds have passed. It is the loop you would otherwise write, minus the loop.

Start in five minutes

Quickstart — a key, an inbox, a message, an assertion.

Wire up CI

Authentication — scopes, workspace reach, rotation without downtime.

Read failures

Errors — the envelope every failure has, and the codes worth branching on.

Coming from Mailosaur

Migrating — what maps across, and what does not yet.

Three things worth knowing before you start

Section titled “Three things worth knowing before you start”

Read status before anything derived from the body. A message accepted over SMTP exists before it is parsed. For a few milliseconds it has no subject, no one-time code and no links. status is what stops “there is no code in this message” and “the code is not extracted yet” from looking identical.

An unknown search criterion is refused, not ignored. Write subjet for subject and you get a 400 naming the field. Ignored, it would have returned every message in the inbox — and your suite would have passed for the wrong reason until the day a second message arrived.

Error messages are in French today. error.code is the contract and it is stable; error.message is a sentence for whoever is reading a red pipeline. Do not parse it.