Aller au contenu
Facteur
/ Produit e-mail

Recevez les e-mails de vos tests, lisez‑les dans vos tests

Votre application envoie un e-mail à l'adresse d'une inbox Facteur, la boîte où arrivent les messages d'un de vos tests. Votre test le récupère par l'API, avec son code, ses liens, ses en-têtes et ses pièces jointes.

facture.spec.ts TypeScript
// Plusieurs critères, tous ou l'un d'eux (match).
const search = new URLSearchParams({
  inbox: 'j3k9x2mq',
  match: 'all',
  sentTo: adresse,
  subject: 'Votre facture',
  since: debutDuTest,
  wait: '20000', // répond dès que le message arrive
});
const auth = { authorization: 'Bearer ' + process.env.FACTEUR_API_KEY };
const { messages } = await (
  await fetch('https://api.facteur.eu/v1/messages?' + search, { headers: auth })
).json();

// Le message lu en entier : rien n'est masqué.
const message = await (
  await fetch('https://api.facteur.eu/v1/messages/' + messages[0].id, { headers: auth })
).json();
message.subject;   // 'Votre facture de juillet'
message.htmlBody;  // le corps HTML
message.textBody;  // sa version texte
message.headers['message-id'];
Un appel HTTP avec une clé en lecture seule : aucun paquet à installer.
otp.spec.ts TypeScript
// Extrait à la réception, pas par vos expressions régulières.
const [message] = messages;
message.otp;      // '265279', le code le plus probable
message.codes;    // tous les nombres de 4 à 8 chiffres
message.links;    // les liens décodés, dans l'ordre du message
message.extract;  // les valeurs définies sur l'inbox

// Le parcours continue avec le code.
await page.getByLabel('Code').fill(message.otp);
await page.getByRole('button', { name: 'Valider' }).click();
Quand plusieurs nombres se disputent et qu'aucun mot n'annonce un code, otp reste vide.
Ce que fait le produit

Du message reçu au test qui passe

01

Une adresse par test

*@<inbox>

Tout ce qui précède l'arobase est libre. Un test qui écrit à inscription+run-42 et un autre à inscription+run-43 reçoivent chacun leur message, dans la même inbox. Chaque message garde l'adresse où il a été envoyé, et votre test filtre dessus.

02

Attendre le message en une requête

GET /messages?wait=

La recherche accepte un délai d'attente : elle ne répond qu'à l'arrivée du message, cinq minutes au plus. Si rien n'arrive, elle répond une liste vide, pas une erreur. Votre test décide si c'est un échec.

03

Le code déjà extrait

message.otp

Le champ otp porte le code à usage unique le plus probable. Le champ codes liste tous les nombres de 4 à 8 chiffres du message. Quand plusieurs nombres se disputent et qu'aucun mot n'annonce un code, Facteur laisse otp vide plutôt que de deviner.

04

Des liens sans échappement

message.links

Un lien écrit en HTML contient &amp; là où l'adresse a un &. Facteur rend les liens décodés, dans l'ordre du message. Votre test passe le premier à son navigateur sans le retoucher.

05

Les pièces jointes

message.attachments

Chaque pièce jointe a son nom, sa taille et son empreinte SHA-256. Votre test compare l'empreinte à celle de son propre fichier, ou télécharge les octets par l'API. Selon l'offre et l'inbox, les octets peuvent ne pas être gardés : la pièce reste alors décrite.

06

Les en-têtes, pour retrouver votre test

message.headers

Ajoutez un en-tête comme X-Test-Id à l'e-mail que votre application envoie, et lisez-le dans le message, en minuscules. Un test retrouve ainsi l'e-mail déclenché par sa propre exécution.

07

Vos propres valeurs, sans expression régulière

message.extract

Pour un identifiant maison, vous sélectionnez la valeur dans un vrai message. Facteur en déduit comment retrouver cette valeur et l'applique aux nouveaux messages de l'inbox.

08

Lire ne coûte rien

Seul un message reçu et gardé compte dans le nombre de messages que comprend votre offre. Un test qui reçoit 3 e-mails et les relit 40 fois en consomme 3, pas 43. La seule limite des lectures est technique : 600 requêtes par minute et par clé d'API.

09

Suppression automatique

Chaque message est supprimé quand la durée de son offre est passée, avec son fichier brut et ses pièces jointes. La suppression passe toutes les heures et ne se désactive pas.

10

Cloisonnement par équipe

workspace

Un espace de travail regroupe des inboxes et les personnes qui y ont accès. Une clé d'API peut être limitée à certains espaces, et chaque inbox peut avoir son propre plafond de messages. La CI de l'équipe A ne lit pas les messages de l'équipe B, et ne vide pas son volume.

Accès

Deux façons d'y accéder

L'API REST couvre tout, et rien n'est à installer pour l'appeler. Reste le cas où c'est le message qui doit vous prévenir, plutôt que l'inverse.

01
En service

API REST

Une API décrite en OpenAPI, avec sa référence publique et ses guides sur le portail des développeurs. L'attente se fait côté serveur et l'extraction à la réception : un test appelle la recherche de messages sans aucune dépendance. Les plugins Playwright et Cypress ne sont pas publiés, et les guides n'en ont pas besoin.

02
Pas encore

Webhooks

Un webhook préviendra votre serveur à chaque message gardé dans une inbox : un appel HTTP signé, qui porte de quoi lire le message par l'API, avec des réessais et le suivi de chaque envoi. La plateforme qui envoie les webhooks n'est pas encore ouverte : aucun webhook ne part aujourd'hui.

Dans un test

Ce que fait un test qui lit un e-mail

  1. Étape 01

    Lancez la recherche

    Elle part avant l'envoi et attend. Elle porte l'inbox, l'adresse visée et la durée d'attente.

    GET /messages inbox, sentTo, wait
  2. Étape 02

    Déclenchez l'envoi

    Votre test clique sur « S'inscrire ». L'application envoie son e-mail à l'adresse de ce test.

  3. Étape 03

    Lisez le code

    La réponse arrive avec le message. Le test saisit le code ou ouvre le premier lien.

    otp: 418302

Écrire le test

Deux guides donnent le fichier complet, pour Playwright et pour Cypress. Les plugins de Facteur pour ces deux outils ne sont pas publiés : les guides appellent l'API directement, avec une clé en lecture seule.