Skip to content
Facteur

Type at least two characters.

Get the code, the links and the headers of a message

Every message that arrives comes with its one-time code, its links and its headers already extracted, with nothing to configure.

A test almost never needs the body of an email. It needs one thing in the body: a six-digit code, a confirmation link, a token. We extract it on reception, and you read it from a field. There is nothing to configure.

The fields you get

Field What it carries
otp The one-time code we judge the most likely, or nothing
codes Every standalone number of 4 to 8 digits in the message, the best candidate first
links Every link of the message, unescaped, in order of appearance, the HTML part first
headers The headers, lower-cased, in the read of a single message
textBody / htmlBody Both versions of the body, as sent, in the read of a single message

A link written in HTML carries entities: & where the URL has an &. A test that follows a still-escaped link asks the server for a URL whose second parameter is called amp;next. It then gets a page that is not the one it expected, and nothing signals the error.

The links the API returns are unescaped. You can pass message.links[0] straight to page.goto() or cy.visit().

When otp is empty and codes is filled

otp is the code that sits closest after a word announcing a code ("code", "verification", "confirmation", "one-time"...), within the sixty characters before it. Without an announcing word, otp is set only when there is a single candidate.

When the message holds several numbers and no announcing word, for example an order number and another six-digit number, we leave otp empty and put the candidates in codes. Guessing which one is right would give you a test that passes until the day the order number changes length.

In that case, point at the value in a real message and let the platform write the pattern: that is the subject of Pointers.

Correlate a message with the run that triggered it

Put a header in the email your application sends (X-Test-Id, X-Correlation-Id), and find it again as is:

const message = await api(`/messages/${id}`);
const mine = message.headers['x-test-id'] === executionId;

Read the key in lower case, always. A header is case-insensitive on the wire: comparing the key as you sent it gives a test that works until the day your sending library changes its capitalization.

Known limits

  • We do not guess your format. A house identifier looks like nothing known. Use a pointer, see Pointers.
  • Codes are numbers of 4 to 8 digits. A code that contains letters does not appear in codes.
  • We do not read the content of attachments. You get their name, size and checksum, see Reading from tests.
  • Nothing is extracted from a refused message. When a limit is reached, the message is recorded with the quota_exceeded status and is not parsed, see Quotas and retention.
  • Extraction happens after the SMTP acknowledgement. A message therefore exists for a few milliseconds with no code or links. Read the status field before the extracted fields, see Reading from tests.