# Runbook: set up Bundle Mail in iPhone Mail, Mac Mail, Outlook or Thunderbird

> For AI agents helping a Bundle member. Human version: https://bundle.direct/blog/bundle-mail-iphone-mac-outlook
> Last checked against Bundle on 2026-10-25.

## Goal

Read and send a person's Bundle mailboxes from a desktop or phone mail app over IMAP/SMTP, using an app password.

## How you act

- The app password is created in the Bundle web app (https://app.bundle.direct) → **Settings → Mail → Mail apps**, in the person's own signed-in session. Any member can do it.
- **The app password is a secret.** Never ask for it in chat and never print it. The human copies it from Bundle into the mail app, or a password manager stores and fills it. The `.mobileconfig` profile contains it too: treat the file as a secret and delete it after installing.
- Installing a profile and adding accounts on a phone or Mac are done by the human (OS confirmation dialogs).

## Prerequisites

- [ ] Bundle Mail is on for the workspace (beta, per workspace). Settings → Mail exists.
- [ ] The person is a member of at least one mailbox.
- [ ] Note: one app password per person per workspace, shared with CalDAV. Creating one replaces the previous one for mail and calendar apps alike. Confirm with the user before creating a new one if they already use CalDAV or a mail app.

## Steps

1. **Settings → Mail → Mail apps → Create app password.** It's shown once (format: four groups of five characters).
2. Choose one:
   - **iPhone / Mac profile:** click **Download iPhone and Mac profile** (only shown right after creating the password). File `Bundle-<workspace>.mobileconfig` configures every mailbox (IMAP `imap.bundle.direct:993` SSL, SMTP `smtp.bundle.direct:465` SSL, user = mailbox address) plus CalDAV (`app.bundle.direct`, user = Bundle account email). **Human step:** iPhone: Settings → Profile Downloaded → Install; Mac: open the file, System Settings → Profiles (Device Management) → Install.
   - **Manual (Outlook, Thunderbird, any IMAP client):**
     - Incoming IMAP: `imap.bundle.direct`, port 993, SSL/TLS
     - Outgoing SMTP: `smtp.bundle.direct`, port 465 SSL/TLS, or 587 STARTTLS; AUTH PLAIN/LOGIN
     - User name: the mailbox address (or one of its aliases; it selects the mailbox)
     - Password: the app password (human enters it)
3. For each additional mailbox (e.g. a shared `hello@`): add another account with that address as the user name and the same app password.

## Behaviour to expect

- Folders: INBOX, Archive, Sent, Drafts, Junk, Trash; labels as `Labels/<name>`. Read (`\Seen`) and star (`\Flagged`) apply to the whole conversation; MOVE moves the conversation; delete → Trash, delete in Trash → gone.
- IDLE push works. Search is substring matching over stored fields.
- Sending: From must be the mailbox or an alias (else SMTP 550). 25 MB per message; per mailbox per day 2,000 messages / 10,000 recipients; 500 recipients per message.
- No OAuth sign-in; no Exchange/ActiveSync.

## Verify

1. The mail app lists INBOX with the same threads as Bundle.
2. Send a test message from the mail app; it appears in Bundle's Sent and is delivered.
3. Mark a message read in the app; the conversation is read in Bundle.

## Rollback / revoke

- Create a new app password in Settings → Mail → Mail apps: every client using the old one stops.
- Or Calendar → Sync with your phone → **Turn off** (deletes the shared password: CalDAV and mail apps both stop).
- **Human step:** remove the profile from the device (iPhone: Settings → General → VPN & Device Management; Mac: System Settings → Profiles) or delete the account in the mail app.
