# 📧 Email Content Extraction — User Guide

<div class="view-markdown-wrapper">
<ViewMarkdown />
</div>

## Overview

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 Email Configuration

1. Navigate to **Settings → Forward Emails**.
2. Click **New Configuration**.
3. Fill in the following fields:
   - **Configuration Name** — e.g., `test user forward`
   - **Forward Email** — an auto-generated address (e.g., `xxxx@forward.shiplight.ai`)
   - **Filter From Email** — the sender’s domain or address (e.g., `@notification.shiplight.ai`)
4. Click **Save**.

💡 **Tip:**  
This generated email address will receive forwarded test emails.  
Make sure your mail provider or automation flow forwards messages to this address. See [Common Email Forwarding Configurations](#common-email-forwarding-configurations) for setup instructions.

## 2. Configure Email Extraction in a Test Case

1. Open your test and **add a new step**: **EXTRACT_EMAIL_CONTENT**.
2. Select the **Forward Email Configuration** 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 Email Configuration** 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 {#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 Config** | Generate a forwarding email address in **Settings → Forward Emails**.  |
| **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`     |