> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anchorbrowser.io/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Anchor Browser provides cloud browsers for AI agents and automation: stealth browsing with residential proxies, managed authentication into third-party web apps, and browser sessions that run reliably at scale. AI agents that need Anchor credentials should start with https://docs.anchorbrowser.io/quickstart/agent-access. This flow lets agents obtain an API key programmatically without creating a dashboard account. Read that page before attempting authentication or API access.

# Email MFA

> Email-based MFA for identity creation, reauthentication, and agent sessions.

Anchor supports one-time password (OTP) as its email MFA method. Each identity is assigned a dedicated mailbox — simply configure a forwarding rule with your email provider to route OTP codes to Anchor during identity creation, reauthentication, and agent sessions.

### Step 1: Add Email MFA as an authentication method

1. Go to the [Identities](https://app.anchorbrowser.io/applications) page and select your identity.
2. Choose **Preset authentication** — the available authentication flows will appear below.
3. Click the **Add flow** button to create a new authentication flow.
4. Enter a name for the flow and click **Add**.
5. Select the **Email MFA** checkbox under **Authentication Methods**. Include any other authentication methods needed for this login flow.
6. Click **Save Changes** in the top-right corner.

### Step 2: Create an identity that uses the Email MFA authentication method

After creating the Email MFA authentication method:

1. Create a new identity.
2. In the credentials window, choose the Email MFA authentication method.
3. You will receive a dedicated mailbox (for example, `zesty-vale7820@mfa.anchorbrowser.io`).
4. Set up a forwarding rule from your mailbox to your dedicated mailbox.
5. Optionally, test the forwarding flow using the detailed instructions.

### Forwarding setup details

Official help for forwarding in common mail clients:

* [Gmail](https://support.google.com/mail/answer/10957)
* [Outlook](https://support.microsoft.com/en-us/office/use-rules-to-automatically-forward-messages-45aa9664-4911-4f96-9663-ece42816d746)

## API Reference

Use the mailbox and identity email APIs to provision an inbox, attach it to an identity, verify forwarding, and read OTP emails programmatically. All endpoints require the `anchor-api-key` header.

### Typical flow

1. Create an [authentication flow](/api-reference/applications/create-authentication-flow) that includes `email_mfa` in `methods`.
2. [Create a mailbox](/api-reference/identities/create-mailbox) to get a dedicated forwarding address.
3. [Create an identity](/api-reference/identities/create-identity) and pass the mailbox `id` as `mailboxId`, plus `authOptionId` for the flow you created.
4. [Send a probe email](/api-reference/identities/send-mailbox-probe) to verify delivery.
5. [List](/api-reference/identities/list-identity-emails) or [read](/api-reference/identities/get-identity-email) emails to retrieve OTP codes.

<Expandable title="Endpoints">
  | Method   | Path                                                 | Description                                        |
  | -------- | ---------------------------------------------------- | -------------------------------------------------- |
  | `POST`   | `/v1/mailboxes`                                      | Create a detached mailbox before identity creation |
  | `GET`    | `/v1/mailboxes/{mailboxId}/emails`                   | List emails received by a mailbox                  |
  | `POST`   | `/v1/mailboxes/{mailboxId}/send-probe`               | Send a test email to verify forwarding             |
  | `POST`   | `/v1/identities/{identityId}/email`                  | Enable or return the identity's mailbox            |
  | `GET`    | `/v1/identities/{identityId}/email`                  | Get the identity's mailbox details                 |
  | `DELETE` | `/v1/identities/{identityId}/email`                  | Detach and delete the identity's mailbox           |
  | `GET`    | `/v1/identities/{identityId}/email/emails`           | List emails in the identity's mailbox              |
  | `GET`    | `/v1/identities/{identityId}/email/emails/{emailId}` | Get full email content (text and HTML)             |
</Expandable>

### Example: provision mailbox and create identity

<CodeGroup>
  ```javascript node.js theme={null}
  import { client, Applications, Identities } from 'anchorbrowser';

  // 1. Create an auth flow with Email MFA
  const authFlow = await Applications.createAuthFlow({
    path: { applicationId },
    body: {
      name: 'Login with Email MFA',
      methods: ['username_password', 'email_mfa'],
    },
  });

  // 2. Create a detached mailbox
  const { data: mailbox } = await client.post({ url: '/v1/mailboxes', body: {} });
  console.log('Forwarding address:', mailbox.address);

  // 3. Create the identity and attach the mailbox
  const identity = await Identities.createIdentity({
    body: {
      name: 'Work Account',
      source: 'https://example.com/login',
      authOptionId: authFlow.id,
      mailboxId: mailbox.id,
      credentials: [
        { type: 'username_password', username: 'user@example.com', password: 'secret' },
      ],
    },
  });
  ```

  ```python python theme={null}
  import os
  from anchorbrowser import Anchorbrowser

  anchor_client = Anchorbrowser(api_key=os.getenv("ANCHOR_API_KEY"))

  auth_flow = anchor_client.applications.create_auth_flow(
      application_id=application_id,
      name="Login with Email MFA",
      methods=["username_password", "email_mfa"],
  )

  mailbox = anchor_client.post("/v1/mailboxes", body={}, cast_to=object)
  print("Forwarding address:", mailbox["address"])

  identity = anchor_client.identities.create_identity(
      name="Work Account",
      source="https://example.com/login",
      credentials=[
          {"type": "username_password", "username": "user@example.com", "password": "secret"},
      ],
      extra_body={"authOptionId": str(auth_flow.id), "mailboxId": mailbox["id"]},
  )
  ```
</CodeGroup>

### Example: test forwarding and read OTP emails

After setting up your email forwarding rule, send a probe to confirm delivery, then poll for incoming messages. Use the `since` query parameter to fetch only emails received after a given ISO timestamp.

<CodeGroup>
  ```javascript node.js theme={null}
  const identityId = 'IDENTITY_ID';
  const mailboxId = 'MAILBOX_ID';

  // Send a probe email to verify forwarding
  await client.post({ url: `/v1/mailboxes/${mailboxId}/send-probe`, body: {} });

  // List recent emails for the identity
  const since = new Date(Date.now() - 5 * 60 * 1000).toISOString();
  const { data: emails } = await client.get({
    url: `/v1/identities/${identityId}/email/emails`,
    query: { since },
  });

  // Read full content of the newest email
  if (emails.length > 0) {
    const { data: email } = await client.get({
      url: `/v1/identities/${identityId}/email/emails/${emails[0].id}`,
    });
    console.log(email.subject, email.body_text);
  }
  ```

  ```python python theme={null}
  import os
  from datetime import datetime, timedelta, timezone
  from anchorbrowser import Anchorbrowser

  anchor_client = Anchorbrowser(api_key=os.getenv('ANCHOR_API_KEY'))
  identity_id = 'IDENTITY_ID'
  mailbox_id = 'MAILBOX_ID'

  anchor_client.post(f'/v1/mailboxes/{mailbox_id}/send-probe', body={}, cast_to=object)

  since = (datetime.now(timezone.utc) - timedelta(minutes=5)).isoformat()
  emails = anchor_client.get(
      f'/v1/identities/{identity_id}/email/emails',
      query={'since': since},
      cast_to=object,
  )

  if emails:
      email = anchor_client.get(
          f'/v1/identities/{identity_id}/email/emails/{emails[0]["id"]}',
          cast_to=object,
      )
      print(email['subject'], email['body_text'])
  ```
</CodeGroup>

<Note>
  During identity creation and agent sessions, Anchor automatically reads OTP codes from the mailbox. Use the list and get email endpoints when you need to handle codes in your own integration.
</Note>

### Related API docs

<CardGroup cols={2}>
  <Card title="Create Mailbox" icon="inbox" href="/api-reference/identities/create-mailbox">
    Provision a dedicated forwarding address
  </Card>

  <Card title="Enable Identity Mailbox" icon="envelope" href="/api-reference/identities/enable-identity-mailbox">
    Attach a mailbox to an existing identity
  </Card>

  <Card title="List Identity Emails" icon="list" href="/api-reference/identities/list-identity-emails">
    Poll for forwarded OTP emails
  </Card>

  <Card title="Send Mailbox Probe" icon="paper-plane" href="/api-reference/identities/send-mailbox-probe">
    Verify forwarding is working
  </Card>
</CardGroup>