Skip to content

Read your first test email

A test that signs a user up ends in a mailbox: the confirmation email holds a code or a link, and the test has to read it. Playwright and Cypress drive a browser, and a browser receives no email. Facteur is the mailbox your application sends to during the test. Your test asks the API for the message, and the code and the links come back already extracted, so nothing in your suite reads an HTML body.

An inbox is a mailbox that your tests read through the API. It receives mail on a whole domain, and each message keeps the exact address it was sent to.

  • You are an owner or an administrator of your Facteur organization. Only these two roles create API keys.
  • You can point your application at an email address of your choosing.
  • You have curl, or any HTTP client.
  1. Open Settings, then API keys, in the Facteur app, and choose Create a key.
  2. Name the key after the place where it runs, for example GitHub CI. In six months, the name tells you which key to revoke.
  3. Leave the read permission on a key that only reads messages. A test suite needs nothing more.
  4. Choose a duration of 30, 90, 180 or 365 days.
  5. Copy the key when it appears. Facteur keeps only a hash of it, so the key is shown once.

Export it in the shell you are about to work in:

Terminal window
export FACTEUR_API_KEY=fk_your_key

Every request carries the key in the Authorization header. This one lists the inboxes the key reaches:

list-inboxes.sh
curl --silent --show-error --fail-with-body \
-H "Authorization: Bearer $FACTEUR_API_KEY" \
https://api.facteur.eu/inboxes

The answer is 200 with a JSON array. An empty array is a valid answer: the key works and the workspaces it reaches hold no inbox yet. Each inbox carries an id of eight characters. That identifier is the first label of its address.

If the answer is 401, the errors guide says which of the three reasons it is.

Point your application at an address of this form:

signup+run-4821@j3k9x2mq.inbox.facteur.eu

Everything before the at sign is yours, and j3k9x2mq is the id of the inbox. Every address that ends with @j3k9x2mq.inbox.facteur.eu arrives in this inbox, and nothing needs creating first. Give each test its own tag after the +, such as a run number or a branch name. Two tests then share one inbox and each reads only its own mail.

search.sh
curl --silent --show-error --fail-with-body --get \
-H "Authorization: Bearer $FACTEUR_API_KEY" \
--data-urlencode "inbox=j3k9x2mq" \
--data-urlencode "sentTo=signup+run-4821" \
--data-urlencode "wait=20000" \
https://api.facteur.eu/messages

wait is a number of milliseconds. While nothing matches, the request stays open for that long, up to five minutes. If nothing has matched at the deadline, the answer is still 200, with an empty list.

A search is a GET request: --get makes curl put each --data-urlencode in the address of the request, and writes the special characters for you. The words you search for are therefore part of that address, and a proxy between your machine and Facteur can write them in its logs. Search for an address, a subject or a code, never for a secret. Limits gives the longest value of each criterion.

A message comes back like this:

{
"messages": [
{
"id": "0198f0a0-7d3e-7000-8000-00000000e2a1",
"inbox": "j3k9x2mq",
"type": "email",
"status": "parsed",
"fromAddress": "no-reply@example.test",
"toAddress": "signup+run-4821@j3k9x2mq.inbox.facteur.eu",
"subject": "Your confirmation code",
"otp": "418302",
"codes": ["418302"],
"links": ["https://example.test/confirm?token=abc"],
"textBody": "Your confirmation code is 418302.",
"htmlBody": "<p>Your confirmation code is <b>418302</b>.</p>",
"receivedAt": "2026-10-13T09:41:07+00:00"
}
],
"nextCursor": null
}

otp is the one-time code Facteur found in the message, and null when there is none. links lists the links of the message in order of appearance. textBody and htmlBody are the two bodies of the message, so a link or a code that no field holds is read from the answer of the search itself, with no second call. status is parsed once every field read from the body is filled in. A search returns parsed messages only, unless you send status=any.

  • Search on sentTo, never on the subject or on “the last message”. Two tests that share an inbox would otherwise read each other’s mail.
  • Put the attempt number in the tag. A retried test then does not read the message of its first attempt and pass for the wrong reason.