Read a message from a test suite
A search sent again every second finds the message as soon as it arrives, fully parsed.
Three routes are enough to write a test.
GET /messages the one you are after, by its criteria
GET /inboxes/<id>/messages the messages of an inbox, newest first
GET /messages/<id> one message, in full
Use the first one. It finds the message by its address or its subject, and hands it back fully parsed.
Before you start
Create an API key from Settings → API keys and send it in a header:
Authorization: Bearer fk_your_key
It needs the ws:read permission. See API keys for what a key reaches and
how to replace one.
Wait for the message: search every second
Every search answers at once. To wait for an email, note the time before the action that sends it, trigger the action, then send the search again every second until the list is not empty:
since="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
# Trigger here the action that sends the email.
for attempt in $(seq 30); do
page="$(curl -sS --fail-with-body --retry 3 -G https://api.facteur.eu/messages \
-H "Authorization: Bearer fk_your_key" \
--data-urlencode "inbox=j3k9x2mq" \
--data-urlencode "sentTo=order-4821-run-17@" \
--data-urlencode "since=$since")"
[ "$(printf '%s' "$page" | jq '.messages | length')" -gt 0 ] && break
sleep 1
done
Facteur almost always parses an email less than a second after it arrives, so the loop
rarely runs more than twice. With the SDK or the Playwright and Cypress plugins you do
not write this loop: waitFor does it for you.
Five things to know:
- Note
sincebefore the action, never after. It keeps out the messages that arrived before, such as the email of an earlier run sent to the same address. Taken after the action, it can leave out a fast email. - Give each test a unique tag, and end
sentTowith@.sentTomatches a part of the address:order-4821also findsorder-48210@…. The final@stops the match at the end of the tag. - The message it returns is fully parsed: subject, one-time code, links.
- Nothing found gives a
200with an empty list, not an error. After how many seconds an absent message is a failure is your test's call. - A key sends 600 requests a minute. A test that waits sends about one a second.
Past that, the answer is
429with aRetry-After: wait that long and go on.--retry 3does it forcurl, and the SDK does it on its own.
If you read an inbox listing instead
GET /inboxes/<id>/messages takes no criteria. The loop then filters on its own:
async function waitFor(inboxId, recipient, timeoutMs = 15000) {
const deadline = Date.now() + timeoutMs;
while (Date.now() < deadline) {
const { messages } = await api(`/inboxes/${inboxId}/messages`);
const found = messages.find((m) => m.toAddress === recipient && m.status === 'parsed');
if (found) return found;
await new Promise((r) => setTimeout(r, 1000));
}
throw new Error(`no message for ${recipient} within ${timeoutMs} ms`);
}
Two details separate a reliable test from a flaky one:
- Filter on
toAddress, not on the subject and not on "the latest message". That is what subaddressing is for, see Inbox addresses. - Require
status === 'parsed'. Otherwise the test occasionally reads a message whose code is not extracted yet, and fails one time in fifty.
Read the status field before any other
status |
What it means | What you do |
|---|---|---|
parsed |
Everything derived from the body is populated | Read the message |
received |
Accepted, not parsed yet | Call the route again: the search GET /messages only returns parsed by default |
quota_ |
Refused: a limit of your plan or of the inbox is reached. Nothing was parsed | See Quotas and retention |
Parsing happens after the SMTP acknowledgement. For a few milliseconds a message therefore exists with no subject, no code and no links. Without this field, "there is no code in this message" and "the code is not extracted yet" look exactly alike.
A refused message omits the extracted fields rather than returning them empty:
message.otp is undefined and not a null you would write an assertion against
that passes for the wrong reason. It carries an errorCode instead, which says which limit refused it.
The shape of a message
{
"id": "…",
"inbox": "ab12cd34",
"receivedAt": "2026-08-07T09:14:02.481Z",
"deliveryMs": 412,
"status": "parsed",
"fromAddress": "no-reply@example.test",
"fromName": "Example",
"toAddress": "signup+7c1e@ab12cd34.inbox.facteur.eu",
"subject": "Your confirmation code",
"textBody": "…",
"htmlBody": "…",
"otp": "418302",
"links": ["https://example.test/confirm?token=…"],
"codes": [],
"headers": { "message-id": "…", "x-your-header": "…" },
"extract": {},
"attachments": [
{
"id": "…",
"fileName": "invoice-4821.pdf",
"contentType": "application/pdf",
"sizeBytes": 86412,
"checksum": "sha256:9f2c…",
"stored": true
}
],
"inlines": []
}
deliveryMs is how long the receiving server took to accept the message. headers,
textBody and htmlBody come with the read of a single message and with a search of the
API (see below), so a test reads its link or its code without a second call. The list of an
inbox leaves them out.
extract carries what the inbox's extractors found, see Pointers.
Search by criteria
curl -G https://api.facteur.eu/messages \
-H "Authorization: Bearer fk_your_key" \
--data-urlencode "inbox=j3k9x2mq" \
--data-urlencode "sentTo=order-4821" \
--data-urlencode "subject=confirmation"
Each criterion is a parameter of the address (-G makes curl put them there, and
--data-urlencode writes the special characters for you). The words you search for are
therefore part of the address of the request, and can be written in the logs of a proxy
or a gateway between your machine and Facteur. Facteur itself does not write them in its
access logs, its application logs or its traces, nor the address of the application page
a search is launched from (the browser sends the name of the site only). The logs of a
component that is not Facteur's are out of its reach. Search for an address, a subject or a code, never for a secret.
Every message of this search carries its textBody, htmlBody and headers. A page of
200 messages with their bodies can be large: ask for fewer with limit when you read
many at once.
The same search can also be sent as a JSON body, with POST /messages/search:
the same criteria, the same longest values, the same codes and the same answer. Use it
when you would rather not put a criterion in an address. When you give both inbox and
workspace, the inbox wins in the two forms.
The criteria. sentTo, sentFrom, subject, body, otp, attachmentName.
They are substrings, case-insensitive. % is not a wildcard and matches only the %
character. otp searches the extracted code and nothing else: body=882314
would also find a message that merely quotes that number.
The bounds. since, hasAttachment and hasOtp narrow the window rather than
adding to the alternatives.
match. all by default: every criterion has to match. Pass any for one to be
enough. A bound never enters the any, otherwise "since yesterday or from Camille"
would hand you messages from the day before.
The longest values. In characters: inbox 36, workspace 40, sentTo and
sentFrom 254, subject, body and attachmentName 255, otp 16. A longer value is
refused with 400 CRITERIA_INVALID, so a text that was cut short never silently matches
the wrong message. A cursor holds 64 characters at most, and a longer one answers
400 INVALID_CURSOR. since is an ISO 8601 date, such as 2026-11-03T10:00:00Z. A true-or-false criterion (hasOtp, hasAttachment)
is written true or false, and limit is a number.
Where to look. inbox for one inbox, workspace (the address of the workspace) for a whole workspace, or
neither for everything your key reaches.
Paging. limit (50 by default, 200 at most) and the nextCursor the response
returns, to pass back in cursor. Pass it back as it is; it is null on the last page, which saves comparing a
count to a limit.
The transitional state. By default the search returns only parsed messages.
Pass status=any to also see the ones that just arrived and the refused ones.
Two refusals that save you an hour
- An unknown criterion is refused, not ignored.
subjetinstead ofsubjectanswers400 CRITERIA_UNKNOWNnaming the field. Ignored, it would have returned every message in the inbox, and your test would have passed for the wrong reason until the day a second message arrives. - An inbox that is not yours answers
404, not an empty list. An empty list reads as "the mail has not arrived" and sends somebody debugging a working pipeline.
Attachments
attachments lists real attachments. inlines lists images referenced by the HTML
body (cid:), almost always a signature logo. The two are kept apart so
attachments.length does not change depending on whether a sender added a banner to
their signature.
Verify content without downloading the file. Compare checksum, which carries the
received file's SHA-256 prefixed with sha256:, against your own local file:
sha256sum invoice-4821.pdf
# 9f2c… invoice-4821.pdf
Download the bytes:
curl -H "Authorization: Bearer fk_your_key" \
https://api.facteur.eu/attachments/<id> -o invoice.pdf
Same access rules as everything else: a key that does not reach the workspace holding
the message gets 404 ATTACHMENT_NOT_FOUND, whether or not an attachment actually
exists under that id.
stored can be false. The file is still described (name, size, checksum) but its
bytes are not kept, and GET /attachments/<id> answers
404 ATTACHMENT_NOT_STORED. The reason field says which of the four cases:
reason |
What it means | What you do |
|---|---|---|
PERFORMANCE_ |
The inbox is set to store nothing | Change the inbox setting if you want the bytes |
TRIAL_ |
The inbox is a trial inbox, which keeps no attachments | Use an inbox of your organization |
ATTACHMENT_ |
The file exceeds what your plan allows | Change plan, or test with a smaller file |
STORAGE_ |
The organization's storage is full | Free up space or buy a storage pack |
Known limits
- No full-text search. The criteria are substrings. Looking for a word with different casing or accents will not find it.