Skip to main content

​
Overview

The WAIT_FOR_EMAIL step polls a test inbox until an email arrives or the timeout is reached. It supports filtering by sender and subject to handle multiple emails.

​
Parameters

​
inbox
string
required
Email address to check for incoming mail. Typically uses a variable from EMAIL_CREATE_INBOX.Example: {{TEST_EMAIL}}
​
timeout
number
default:"60"
Maximum time to wait for email arrival in seconds. Range: 1-300 seconds.
​
fromAddress
string
Filter emails by sender address (partial match supported).Examples:
  • noreply@ - Matches any noreply address
  • [email protected] - Exact match
  • @company.com - Matches any sender from company.com
​
subject
string
Filter emails by subject line (partial match supported).Examples:
  • Welcome - Matches “Welcome to our app”
  • Reset - Matches “Password Reset Request”
  • Order # - Matches any order confirmation
​
storeAs
string
Variable name to store the received email data for extraction in subsequent steps.

​
Behavior

  1. Polling: Checks inbox every 2 seconds for new emails
  2. Filtering: Applies sender/subject filters if specified
  3. First Match: Returns the first email matching all criteria
  4. Timeout: Fails if no matching email arrives within timeout
  5. Data Storage: Stores complete email data if storeAs is provided

​
Email Data Structure

The stored email data contains:
  • id: Unique email identifier
  • subject: Email subject line
  • from: Sender email address
  • to: Recipient email address
  • text: Plain text email body
  • html: HTML email body
  • headers: Message headers including Message-ID and Date
  • received_at: Timestamp when email was received

​
Common Use Cases

  • Waiting for account verification emails
  • Catching password reset emails
  • Receiving order confirmations
  • Getting notification emails
  • Handling multi-step email workflows

​
Examples

​
Basic Email Wait

  • Step type: WAIT_FOR_EMAIL
  • Inbox:
  • Timeout: 30 seconds
  • Store as: RECEIVED_EMAIL

​
With Subject Filter

  • Step type: WAIT_FOR_EMAIL
  • Inbox:
  • Subject: “Verify your account”
  • Timeout: 60 seconds
  • Store as: VERIFY_EMAIL

​
With Sender Filter

  • Step type: WAIT_FOR_EMAIL
  • Inbox:
  • From address: [email protected]
  • Timeout: 45 seconds
  • Store as: ORDER_EMAIL

​
Multiple Filters

  • Step type: WAIT_FOR_EMAIL
  • Inbox:
  • From address: [email protected]
  • Subject: “Welcome”
  • Timeout: 30 seconds
  • Store as: WELCOME_EMAIL

​
Extended Timeout for Slow Systems

  • Step type: WAIT_FOR_EMAIL
  • Inbox:
  • Subject: “Weekly Report”
  • Timeout: 120 seconds (for scheduled emails)
  • Store as: REPORT_EMAIL

​
Best Practices

  1. Set Appropriate Timeouts: 30-60 seconds for most emails
  2. Use Filters: When expecting multiple emails
  3. Store Email Data: Always use storeAs for extraction
  4. Handle Delays: Account for email delivery delays
  5. Specific Subjects: Use unique subjects when possible
Email delivery times can vary. Set timeouts generously to avoid flaky tests, especially in CI/CD environments.

​
Error Handling

Common causes:
  • Email delivery delayed beyond timeout
  • Filters too restrictive
  • Application didn’t send email
  • Wrong inbox address
Solutions:
  • Increase timeout value
  • Check filter accuracy
  • Verify application behavior
  • Confirm inbox address
The step returns the first matching email. Use specific filters to target the correct email when multiple matches are possible.

​
Troubleshooting

​
Debug Tips

  1. Remove Filters: Start without filters to see all emails
  2. Check Timing: Ensure email trigger happens before wait
  3. Verify Inbox: Confirm correct email address is used
  4. Log Email Data: Store and log email data for debugging

​
Common Patterns

Wait for any email (debugging):
  • Step type: WAIT_FOR_EMAIL
  • Inbox:
  • Timeout: 30 seconds
  • Store as: ANY_EMAIL
Then use a JavaScript step to log the email data for debugging purposes.