Skip to content
Facteur

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.

invoice.spec.ts TypeScript
// 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'];
One HTTP call with a read-only key: no package to install.
otp.spec.ts TypeScript
// 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();
When several numbers compete and no word announces a code, otp stays empty.

From the received message to the passing test

01

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.

02

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.

03

The code, already extracted

message.otp

The 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.

04

Links without escaping

message.links

A link written in HTML contains &amp; 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.

05

Attachments

message.attachments

Each 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.

06

Headers, to find your test again

message.headers

Add 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.

07

Your own values, without a regular expression

message.extract

For 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.

08

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.

09

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.

10

Isolation per team

workspace

A 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.

01
In service

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.

02
Not yet

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

  1. 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
  2. Step 02

    Trigger the send

    Your test clicks "Sign up". The application sends its email to the address of that test.

  3. 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.