Email Mailbox
Test email workflows like OTP codes, magic links, and password resets
When You Need It
Many app flows send emails that users must act on. If your test involves any of these, you need mailbox integration:
| Use Case | What the test does |
|---|---|
| Email OTP / Verification Code | Sign up, receive a verification email, extract the 4-8 digit code, type it in |
| Magic Link Login | Trigger a magic link email, extract the link, navigate to it |
| Password Reset | Request a password reset, extract the reset URL from the email, complete the reset |
| Team/User Invitation | Send an invite, extract the accept link from the email, click to accept |
| Transactional Email Verification | Trigger a transactional email (order confirmation, receipt), verify it arrived with the right content |
| Email Content Assertions | Assert that an email's subject, body, or sender matches expected values |
| Link Extraction | Extract any action link from an email — confirm account, unsubscribe, approve request |
| Multi-step Email Chains | Approval workflows where multiple emails are sent in sequence |
| Deliverability Check | Verify that an email was sent at all within a timeout |
Configuring Mailboxes
Connect one or more email inboxes in Settings → Integrations → Email Mailbox. Each mailbox has a name you'll reference in your test steps (e.g. signup-inbox, admin-inbox).
Provider Options
| Provider | What you need |
|---|---|
| Gmail | Your Gmail address and an App Password (not your regular password) |
| Outlook | Your Outlook address and an App Password |
| Custom IMAP | IMAP host, port, username, password, and whether TLS is enabled |
For Gmail users: you need to generate an App Password in your Google Account settings. This is a 16-character password specifically for third-party apps. Your regular Gmail password won't work with IMAP.
Setup Steps
- Go to Settings → Integrations → Email Mailbox
- Click Add Mailbox
- Give it a name (e.g.
signup-inbox) - Select your provider (Gmail, Outlook, or Custom IMAP)
- Enter your credentials
- Click Test Connection to verify it works
- Click Save
You can add multiple mailboxes — for example, one for the user signing up and another for an admin receiving notifications.
Credentials are encrypted at rest and scoped to your organization. They are never logged or included in test traces.
Email Steps
Three new step types are available in the step palette under the Email category.
Wait for Email
Polls a named mailbox for a matching email.
| Field | Description |
|---|---|
| Mailbox | Name of the mailbox to poll (as configured in Settings) |
| Subject contains | Substring or regex to match the email subject |
| From | Sender email address to filter by |
| Timeout | How long to wait before failing the step (default: 60 seconds) |
| Save to variable | Variable name to store the full email object |
The step polls the specified mailbox repeatedly until it finds a matching email or the timeout is reached. When found, the full email (subject, body text, body HTML, sender, date) is stored in the specified variable for use in later steps.
If no matching email arrives within the timeout, the step fails.
Extract from Email
Extracts an OTP code, link, or text from an email stored in a variable.
| Field | Description |
|---|---|
| Email variable | The variable from a previous Wait for Email step |
| Extract type | What to extract: OTP Code, Link, or Text |
| Pattern | For OTP: the digit count (e.g. 6). For Link/Text: a regex pattern |
| Save to variable | Variable name to store the extracted value |
Use this after a Wait for Email step. It reads the email from the variable you specify and extracts the value you need:
- OTP Code — Finds a numeric code of the specified length (e.g. 6 digits) in the email body
- Link — Finds a URL matching your pattern (e.g.
https://app.com/verify.*) - Text — Extracts arbitrary text using a regex with a capture group
The extracted value is saved to a variable you can use in subsequent Type or Navigate steps.
Assert Email
Asserts that an email's content matches your expectations.
| Field | Description |
|---|---|
| Email variable | The variable from a previous Wait for Email step |
| Subject matches | Regex the subject should match |
| Body contains | Text the email body should contain |
| From matches | Expected sender email or pattern |
All three fields are optional — you can assert on any combination. The step passes if all specified conditions match, and fails with details about what didn't match.
End-to-End Example
Here's a complete test for sign-up with email verification:
Step 1: Navigate → https://app.com/signup
Step 2: Type → "test@gmail.com" into email field
Step 3: Type → "Password123" into password field
Step 4: Click → "Sign Up" button
Step 5: Wait for Email → mailbox "signup-inbox", subject contains "Verification", save to {{verificationEmail}}
Step 6: Extract from Email → OTP (6 digits) from {{verificationEmail}}, save to {{otpCode}}
Step 7: Type → {{otpCode}} into OTP input
Step 8: Click → "Verify" button
Step 9: Assert AI → "User is logged in and sees dashboard"
Steps 1-4 trigger the sign-up flow. Step 5 waits for the verification email to arrive. Step 6 pulls out the OTP code. Steps 7-8 complete the verification. Step 9 confirms success.
You can use the same pattern for magic links (extract a link instead of an OTP, then use a Navigate step) or password resets.
Tips
- Timeouts — Set your Wait for Email timeout based on how fast your app sends emails. 30-60 seconds is a good default. Transactional email services are usually fast, but some apps batch or delay emails.
- Subject filters — Be specific enough to avoid matching the wrong email, especially if the inbox receives other messages. Combine subject and from filters when possible.
- Parallel test runs — If multiple test runs share the same inbox, emails are filtered by timestamp so each run only sees emails sent after the test started. No cross-contamination.
- Gmail rate limits — Gmail allows roughly 15 concurrent IMAP connections. If you run many tests in parallel against the same Gmail inbox, you may hit this limit. Consider using separate inboxes for parallel suites.
- Connection reuse — Within a single test run, the IMAP connection is reused across multiple email steps. You don't need to worry about connection overhead.