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.
Before you begin
Section titled “Before you begin”- 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. Create an API key
Section titled “1. Create an API key”- Open Settings, then API keys, in the Facteur app, and choose Create a key.
- Name the key after the place where it runs, for example
GitHub CI. In six months, the name tells you which key to revoke. - Leave the read permission on a key that only reads messages. A test suite needs nothing more.
- Choose a duration of 30, 90, 180 or 365 days.
- 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:
export FACTEUR_API_KEY=fk_your_key2. Check that the key works
Section titled “2. Check that the key works”Every request carries the key in the Authorization header. This one lists the inboxes the key reaches:
curl --silent --show-error --fail-with-body \ -H "Authorization: Bearer $FACTEUR_API_KEY" \ https://api.facteur.eu/inboxesThe 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.
3. Send mail to the inbox
Section titled “3. Send mail to the inbox”Point your application at an address of this form:
signup+run-4821@j3k9x2mq.inbox.facteur.euEverything 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.
4. Wait for the message
Section titled “4. Wait for the message”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/messageswait 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.
Keep the test from going flaky
Section titled “Keep the test from going flaky”- 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.
Next steps
Section titled “Next steps”- Receive email in a Playwright test and in a Cypress test wire these steps into a real test.
- Authentication covers the four permissions of a key and the workspaces it reaches.
- Limits lists the ceilings a parallel suite meets.
- The API reference describes every operation.