Receive the emails of your tests, read them in your tests
Your application sends an email to the address of a Facteur inbox, the box where the messages of one of your tests arrive. Your test fetches it through the API, with its code, its links, its headers and its attachments.
// Several criteria, all of them or any of them (match).
const search = new URLSearchParams({
inbox: 'j3k9x2mq',
match: 'all',
sentTo: address,
subject: 'Your invoice',
since: startOfTest, // only a message that arrives after it counts
});
const auth = { authorization: 'Bearer ' + process.env.FACTEUR_API_KEY };
const { messages } = await (
await fetch('https://api.facteur.eu/messages?' + search, { headers: auth })
).json();
// The whole message: nothing is hidden.
const message = await (
await fetch('https://api.facteur.eu/messages/' + messages[0].id, { headers: auth })
).json();
message.subject; // 'Your July invoice'
message.htmlBody; // the HTML body
message.textBody; // its text version
message.headers['message-id'];
// Extracted on arrival, not by your regular expressions.
const [message] = messages;
message.otp; // '265279', the most likely code
message.codes; // every number of 4 to 8 digits
message.links; // the links, decoded, in the order of the message
message.extract; // the values defined on the inbox
// The journey carries on with the code.
await page.getByLabel('Code').fill(message.otp);
await page.getByRole('button', { name: 'Confirm' }).click();
From the received message to the passing test
One address per test
*@<inbox>Everything before the at sign is yours. A test writing to signup+run-42 and another writing to signup+run-43 each get their own message, in the same inbox. Every message keeps the address it was sent to, and your test filters on it.
Wait for the message without a fixed pause
GET /messages?since=The search answers at once. Your test sends it again every second, or lets a plugin do it, and reads the message as soon as it arrives. If nothing arrives, it answers an empty list, not an error. Your test decides whether that is a failure.
The code, already extracted
message.otpThe otp field carries the most likely one-time code. The codes field lists every number of 4 to 8 digits in the message. When several numbers compete and no word announces a code, Facteur leaves otp empty rather than guess.
Links without escaping
message.linksA link written in HTML contains & where the address has an &. Facteur returns the links decoded, in the order of the message. Your test hands the first one to its browser untouched.
Attachments
message.attachmentsEach attachment has its name, its size and its SHA-256 checksum. Your test compares the checksum with the one of its own file, or downloads the bytes through the API. Depending on the plan and the inbox, the bytes may not be kept: the attachment is then still described.
Headers, to find your test again
message.headersAdd a header such as X-Test-Id to the email your application sends, and read it back in the message, in lower case. A test finds the email triggered by its own run.
Your own values, without a regular expression
message.extractFor a house identifier, you select the value in a real message. Facteur works out how to find that value and applies it to the new messages of the inbox.
Reading costs nothing
Only a message that is received and kept counts toward the number of messages your plan includes. A test that receives 3 emails and rereads them 40 times uses 3, not 43. The only limit on reads is technical: 600 requests per minute per API key.
Automatic deletion
Every message is deleted once the duration of its plan has passed, with its raw file and its attachments. Deletion runs every hour and cannot be turned off.
Isolation per team
workspaceA workspace groups inboxes and the people who can reach them. An API key can be limited to some workspaces, and each inbox can have its own ceiling of messages. Team A's CI does not read team B's messages, and does not drain its volume.
Two ways in
The REST API covers everything, and nothing needs installing to call it. That leaves the case where the message should tell you, rather than the other way round.
REST API
An API described in OpenAPI, with its public reference and its guides on the developer portal. The extraction happens on reception: a test calls the message search every second, with no dependency at all. The Playwright and Cypress plugins install from npm, and the guides do not need them.
Webhooks
A webhook will tell your server about every message kept in an inbox: a signed HTTP call carrying what it takes to read the message through the API, with retries and a record of each delivery. The platform that sends webhooks is not open yet: no webhook leaves today.
What a test that reads an email does
-
Step 01
Start the search
It leaves before the send and waits. It carries the inbox, the address aimed at and how long to wait.
GET /messages inbox, sentTo, wait -
Step 02
Trigger the send
Your test clicks "Sign up". The application sends its email to the address of that test.
-
Step 03
Read the code
The answer arrives with the message. The test types the code or opens the first link.
otp: 418302
Write the test
Two guides give the whole file, for Playwright and for Cypress. They call the API directly, with a read-only key. The Facteur plugins for these two tools also install from npm.