# Read an inbox in your mail app (IMAP)

Source: https://agentboxd.com/docs/imap

> Add an agent’s inbox to Apple Mail, Outlook or Thunderbird with an app password, read-only, to see what your agent sees.

Want to keep an eye on what your agent receives, in the mail app you already use? Add the inbox as an IMAP account. Your mail app gets its own password for that one inbox, and it can read mail but never change it: no sending, deleting, moving or marking as read.

## Create an app password

- Open the inbox in the dashboard, then **Settings › Read in your mail app (IMAP)**.
- Under **App passwords**, give it a name (the device, like “MacBook Mail”), choose when it expires, and press **Create app password**. Only workspace owners can create and revoke them.
- Copy the password (`ap_…`). It is shown once: we keep only a hash of it. Lost it? Revoke it and create a new one.

Create one password per device. Revoking one stops that device at once, and the others keep working. An inbox can have up to 10 at a time; the list shows when each was last used.

## Settings

| Setting | Value |
| --- | --- |
| Account type | IMAP |
| Server | `imap.agentboxd.com` (the name shown in the inbox Settings) |
| Port | `993` |
| Security | SSL/TLS (not STARTTLS; there is no unencrypted port) |
| Authentication | Normal password |
| Username | The full inbox address, as shown at the top of the inbox |
| Password | The app password (`ap_…`). Never your own password or a sign-in link: they don’t work here |

Mail apps also ask for an outgoing (SMTP) server, because they expect to send. This account is for reading: reply through your agent or the dashboard. If your app won’t save the account without a working outgoing server, use [SMTP](https://agentboxd.com/docs/smtp) (`smtp.agentboxd.com`, port `465` or `587`) with an inbox-scoped API key that has only `messages:send` as its password; what you send then goes through the same checks as an API send.

## Apple Mail

- On a Mac: **Mail › Settings › Accounts**, press **+**, choose **Other Mail Account…** and **Continue**.
- Enter a name, the inbox address and the app password, then **Sign In**. Mail can’t guess the servers, so it asks for them.
- Choose **IMAP** as the account type, enter `imap.agentboxd.com` as the incoming mail server and the inbox address as the user name, then **Sign In** again. For the outgoing server, see above.
- Keep only **Mail** ticked and press **Done**. Mail uses SSL on port 993 by default; if it doesn’t connect, open the account’s **Server Settings**, untick automatic settings and set port `993` with **Use TLS/SSL**.
- On an iPhone or iPad: **Settings › Apps › Mail › Mail Accounts › Add Account › Other › Add Mail Account**, then the same values under **IMAP**.

## Outlook

- New Outlook for Windows and Outlook for Mac: **Settings › Accounts › Add account**, enter the inbox address, and choose **IMAP** when asked for the account type (open the advanced or manual settings if Outlook doesn’t offer it).
- Incoming (IMAP) server `imap.agentboxd.com`, port `993`, secure connection **SSL/TLS**, the inbox address as user name and the app password as password.
- Outgoing server: see above. Then **Continue** or **Sign in**.
- Classic Outlook for Windows: **File › Add Account › Advanced options › Let me set up my account manually › IMAP**, with the same values.

## Thunderbird

- In the menu: **Account Settings › Account Actions › Add Mail Account** (or **New › Existing Email Account**).
- Enter a name, the inbox address and the app password, then **Configure manually**.
- Incoming server: protocol **IMAP**, hostname `imap.agentboxd.com`, port `993`, connection security **SSL/TLS**, authentication **Normal password**, username the inbox address.
- Outgoing server: see above. Press **Re-test**, then **Done**.

## What you see

- Two folders: **Inbox** (received mail) and **Sent** (what the agent sent). Each message is exactly as it arrived or left, attachments included.
- In a workspace that gives agents only screened mail (the default), your mail app follows the same rule: mail held for review, or still being checked, isn’t shown. When someone releases it in the dashboard, it arrives in your mail app as new mail.
- Read and unread come from the dashboard. Reading a message in your mail app doesn’t mark it read for your agent or in the dashboard.
- New mail shows up within about 30 seconds while the app is open (IMAP IDLE), or when the app next checks.
- Search in the app works on subject, sender and recipients; body search matches whole words.
- Mail removed by your retention setting disappears from your mail app too.

## Limits and errors

| Message from your mail app | Why |
| --- | --- |
| Invalid credentials | Wrong username or password. The username is the full inbox address; the password is an app password, revoked ones don’t work |
| This app password expired | Its expiry date passed: create a new one |
| Too many failed logins | After 10 wrong passwords from your network (or 20 for one address) within 15 minutes, logins are refused for 15 minutes |
| Too many connections to this inbox | Up to 10 connections per inbox at once; close the inbox in another app or device |
| … is not allowed: this mailbox is read-only | Your app tried to delete, move, flag or upload a message. Nothing changed |

> **Careful:** An app password reads every message of its inbox. Treat it like a password: give each device its own, set an expiry when you can, and revoke one as soon as a device is lost.