Email Extraction

View as Markdown

The Email Content Extraction feature allows your automated tests to automatically read incoming emails and extract specific content: such as verification codes, activation links, or any custom information.

This process is powered by an LLM-based extractor, which understands natural language and automatically identifies the required content: no regex or complex setup needed.

1. Create a Forward Address

1. Go to Settings → Email Forwarding.
2. Click + Create.
3. Enter a label (e.g. signup emails) and save.

You get an auto-generated address like xxxx@forward.shiplight.ai. Any email forwarded there becomes available to your tests. Configure your app's mail provider to forward the relevant messages to this address. See Common Email Forwarding Configurations for setup instructions.

2. Configure Email Extraction in a Test Case

There are two ways to add this step: tell your coding agent, or add it manually.

Tell your coding agent

When authoring or running a test, just give your agent the forward address and what to extract:

Use the forward address xxxx@forward.shiplight.ai to grab the activation
link from the signup email, then navigate to it to finish registration.

The agent adds the extraction step and wires the result into the following steps.

Add it manually

1. Open your test and add a new step: EXTRACT_EMAIL_CONTENT.
2. Select the forward address you created earlier.
3. Choose the Extraction Type: one of:
   • Verification Code → extracts numeric codes
     • Output variable: email_otp_code
   • Activation Link → extracts a link (e.g., a login or verification URL)
     • Output variable: email_magic_link
   • Custom → extracts any text based on a custom instruction
     • Output variable: email_extracted_content
4. (Optional) For Custom type, fill in the Prompt field with a short natural language description of what you want, e.g.:

   "Extract the temporary password from the email body."

5. Configure filters:
   • Filter From Email — required sender address or domain.
   • Filter To Email, Filter Subject, Filter Body Contains — optional filters to narrow down the target email.

3. Dynamic Variable Support in Filters

All filter fields support referencing variables defined in your test case. Use variables to dynamically filter based on runtime values.

Syntax

• $variableName
• $.variableName

Example

Filter Subject: Welcome $username
Filter Body Contains: Code sent to $.email

At runtime, $username and $.email will be replaced with the actual test variable values.

4. Using Extracted Results in Tests

When an email is matched and processed, the extracted result is automatically stored in a variable depending on the Extraction Type.

Extraction Type	Variable Name	Description
Verification Code	email_otp_code	The numeric verification code extracted from the email.
Activation Link	email_magic_link	The link (URL) extracted from the email body.
Custom	email_extracted_content	The text or content extracted based on the custom prompt.

You can reference these variables directly in later steps of your test.

Example Usages

• Navigate to an activation link:

  navigate to email_magic_link

• Input a verification code:

  input email_otp_code into verification code input field

• Use custom extracted content:

  input email_extracted_content into text input field

  Or simply describe it in your test steps as "use the content extracted from the email."

5. Example Scenario

Goal: Automatically complete a login flow using a magic link received by email.

1. Create a forward address for sender @notification.shiplight.ai.
2. Add a test step: EXTRACT_EMAIL_CONTENT
   • Extraction Type: Activation Link
   • Output Variable: email_magic_link
3. Add a NAVIGATE step:

   navigate to email_magic_link

4. Run the test. The test automatically waits for the forwarded email, extracts the link, and navigates to it to complete login.

6. Example UI Reference

Step 1: EXTRACT_EMAIL_CONTENT
→ custom
→ From: @notification.shiplight.ai
→ Variable: email_extracted_content

Step 2: NAVIGATE
→ navigate to email_extracted_content

This setup extracts custom text from the email and uses it directly in the next action.

7. Common Email Forwarding Configurations

Here's how to configure forwarding from popular email services to your Shiplight Forward Email address (e.g., xxxx@forward.shiplight.ai).

🟢 Gmail (Google Mail)

1. Go to Settings → See all settings → Forwarding and POP/IMAP.
2. Click Add a forwarding address.
3. Enter your generated Shiplight forwarding email (e.g., xxxx@forward.shiplight.ai).
4. Gmail will send a verification email: you can skip actual verification for test accounts or complete it via test flow.
5. After adding, select Forward a copy of incoming mail to... and choose whether to keep or delete Gmail copies.
6. Save changes.

Optional: Use Gmail filters to forward only specific messages (e.g., from @notification.shiplight.ai).

🔵 Outlook / Microsoft 365

1. Go to Settings → View all Outlook settings → Mail → Rules.
2. Add a new rule:
   • Condition: From contains @notification.shiplight.ai
   • Action: Forward to xxxx@forward.shiplight.ai
3. Save the rule.
4. Make sure forwarding is enabled for your account (check admin policy if needed).

🟣 Yahoo Mail

1. Go to Settings → More Settings → Mailboxes.
2. Select your account, scroll to Forwarding, and add your Shiplight forward address.
3. Confirm via Yahoo's verification email.
4. Save.

🟠 Custom / Corporate Mail Servers (e.g., Exchange, Zoho, or Company Domain)

You can usually add a forwarding rule via:

• Mail routing rules in admin settings, or
• User-level forwarding in account preferences.

Typical configuration:

• Condition: From contains @notification.shiplight.ai
• Action: Forward to xxxx@forward.shiplight.ai
• Keep a copy: Optional depending on test needs.

8. Best Practices

• Always filter by sender using Filter From Email to prevent unrelated messages from being processed.
• Use test variables ($, $.) to dynamically adjust filters like subject or body content.
• Keep prompts clear and concise when using "Custom" extraction: LLMs perform best with specific instructions.
• Avoid forwarding sensitive production data: use only test environments or mock email accounts.
• Create separate configurations for different types of emails (sign-up, reset, notifications, etc.) for easier maintenance.

9. Summary

Step	Description
1. Create Forward Address	Generate a forwarding email address in Settings → Email Forwarding.
2. Add Extraction Step	Add EXTRACT_EMAIL_CONTENT and select extraction type.
3. Use Variables	Reference the output variable in later steps.
4. Dynamic Filters	Use $ or $. variables for dynamic subjects or recipients.
5. LLM Extraction	No regex required: the system understands and extracts intelligently.
6. Email Setup	Configure your email provider to forward test emails to Shiplight.

10. Quick Reference: Variables

Extraction Type	Variable Name	Example Use
Verification Code	email_otp_code	input email_otp_code into verification code input field
Activation Link	email_magic_link	navigate to email_magic_link
Custom	email_extracted_content	input email_extracted_content into text input field