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

# Mailboxes

> Give your agent an inbox and retrieve email verification codes.

Part of the [Identity stack](https://docs.mobilerun.ai/identity/overview.md): an API-first, plug-and-play inbox layer for your agent's phone.

Mailboxes give your agent an email address for app signups, verification codes, and incoming messages.
Use a managed mailbox or connect an inbox you already own.

## Get a mailbox

Open the mailboxes section of the [dashboard](https://cloud.mobilerun.ai) to create an address or connect
an existing inbox. For the [SDK](https://docs.mobilerun.ai/guides/sdk-objects.md), set `MOBILERUN_API_KEY` and check included capacity:

```typescript TypeScript theme={null}
import { MobilerunSDK } from '@mobilerun/sdk';

const mobilerun = new MobilerunSDK(); // Reads MOBILERUN_API_KEY.

console.log(await mobilerun.mailboxes.capacity());
const mailbox = await mobilerun.mailboxes.create({ billingPreference: 'included_only' });
console.log(mailbox.id, mailbox.address, mailbox.status);
```

```python Python theme={null}
from mobilerun_sdk import MobilerunSDK

mobilerun = MobilerunSDK()  # Reads MOBILERUN_API_KEY.

print(mobilerun.mailboxes.capacity())
mailbox = mobilerun.mailboxes.create(billing_preference="included_only")
print(mailbox.id, mailbox.address, mailbox.status)
```

`included_only` fails if no included slot remains. `included` uses included capacity when available and
otherwise starts paid checkout; `rent` always starts paid checkout. Paid rentals can incur charges.
If a mailbox is still provisioning, retrieve it again; a checkout URL may arrive in a later response.
Complete `data.checkoutUrl` (Python `data.checkout_url`) before using an `awaiting_payment` mailbox.

## Use it with a phone

Enter the mailbox address into the signup or sign-in screen on your [phone](https://docs.mobilerun.ai/devices.md). Wait for the OTP
when the app sends its verification email. This example uses an existing mailbox and creates nothing:

```typescript TypeScript theme={null}
import { MobilerunSDK } from '@mobilerun/sdk';

const mobilerun = new MobilerunSDK(); // Reads MOBILERUN_API_KEY.

const mailbox = mobilerun.mailboxes.fromId('MAILBOX_ID');
console.log(await mailbox.waitForOtp());
```

```python Python theme={null}
from mobilerun_sdk import MobilerunSDK

mobilerun = MobilerunSDK()  # Reads MOBILERUN_API_KEY.

mailbox = mobilerun.mailboxes.from_id("MAILBOX_ID")
print(mailbox.wait_for_otp())
```

The wait polls for up to two minutes by default and only considers codes received after the wait starts,
unless you pass `after`. The comparison uses your computer's clock. The result contains the code,
received time, sender, message ID, and confidence. Use the code in the phone's verification screen.

## Read results

Read message summaries, then retrieve a particular message for its full content:

```typescript TypeScript theme={null}
import { MobilerunSDK } from '@mobilerun/sdk';

const mobilerun = new MobilerunSDK(); // Reads MOBILERUN_API_KEY.

console.log(await mobilerun.api.mailboxes.messages.list('MAILBOX_ID'));
console.log(await mobilerun.api.mailboxes.messages.retrieve('MESSAGE_ID', { mailboxId: 'MAILBOX_ID' }));
```

```python Python theme={null}
from mobilerun_sdk import MobilerunSDK

mobilerun = MobilerunSDK()  # Reads MOBILERUN_API_KEY.

print(mobilerun.api.mailboxes.messages.list("MAILBOX_ID"))
print(mobilerun.api.mailboxes.messages.retrieve("MESSAGE_ID", mailbox_id="MAILBOX_ID"))
```

### Bring your own inbox

Start a connection and open the returned redirect URL to authorize access in your browser. The API's
`provider` field selects the supported inbox type; it is not a managed mailbox purchase.

```typescript TypeScript theme={null}
import { MobilerunSDK } from '@mobilerun/sdk';

const mobilerun = new MobilerunSDK(); // Reads MOBILERUN_API_KEY.

const connection = await mobilerun.mailboxes.connections.create({ provider: 'gmail' });
console.log(connection.info); // Open redirectUrl, then poll the connection.
```

```python Python theme={null}
from mobilerun_sdk import MobilerunSDK

mobilerun = MobilerunSDK()  # Reads MOBILERUN_API_KEY.

connection = mobilerun.mailboxes.connections.create(provider="gmail")
print(connection.info)  # Open redirect_url, then poll the connection.
```

## Costs and cancellation

Included capacity comes from your plan; check the dashboard for current paid rental pricing. Cancelling
retains existing addresses and messages. Restarting an archived mailbox keeps its address and can use
included capacity or require paid checkout. These are separate lifecycle operations:

```typescript TypeScript theme={null}
import { MobilerunSDK } from '@mobilerun/sdk';

const mobilerun = new MobilerunSDK(); // Reads MOBILERUN_API_KEY.

await mobilerun.api.mailboxes.delete('MAILBOX_ID');
```

```python Python theme={null}
from mobilerun_sdk import MobilerunSDK

mobilerun = MobilerunSDK()  # Reads MOBILERUN_API_KEY.

mobilerun.api.mailboxes.delete("MAILBOX_ID")
```

```typescript TypeScript theme={null}
import { MobilerunSDK } from '@mobilerun/sdk';

const mobilerun = new MobilerunSDK(); // Reads MOBILERUN_API_KEY.

await mobilerun.api.mailboxes.restart('MAILBOX_ID', { billingPreference: 'included_only' });
```

```python Python theme={null}
from mobilerun_sdk import MobilerunSDK

mobilerun = MobilerunSDK()  # Reads MOBILERUN_API_KEY.

mobilerun.api.mailboxes.restart("MAILBOX_ID", billing_preference="included_only")
```

For a connected external inbox, disconnect the mailbox link instead of cancelling a rental.

## API reference

See [Mailbox](https://docs.mobilerun.ai/api-reference/mailboxes/list-mailboxes.md) for capacity, checkout, OTP, and lifecycle endpoints.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.