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 |
Follow a link without unescaping it yourself
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_exceededstatus 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
statusfield before the extracted fields, see Reading from tests.