Connect a mailbox

fob-email signs in to your mailbox the way a desktop mail app does: an IMAP server name, your username, and a password. For almost every provider, that password must be an app password, a separate password you create in your account's security settings. Your normal sign-in password is usually rejected.

Video coming soon

Connect Gmail to fob-email (2–3 min)

What you need#

	Example (Gmail)	Where to find it
IMAP server	`imap.gmail.com`	Providers
SMTP server, to send mail	`smtp.gmail.com`	Providers
Username	`[email protected]`	Usually your full address. iCloud is the exception
App password	16 characters	Your provider's security settings. See Providers

Microsoft-hosted mailboxes (Outlook.com, Hotmail, Microsoft 365) can't connect, because they require OAuth sign-in. See Outlook and Microsoft 365.

1. Create an app password#

Follow the steps for your provider in Providers. Copy the password when it's shown: most providers show it only once.

2. Add the account#

Pick a short name for the mailbox, such as personal or work. It's how you'll refer to it later with --account.

fob-email config accounts add personal \
  --imap-host imap.gmail.com \
  --imap-user [email protected] \
  --imap-pass "<app password>" \
  --smtp-host smtp.gmail.com

--imap-port defaults to 993 and --smtp-port to 465, both with TLS. That suits most providers.
Pass --smtp-host if you want to send mail. SMTP reuses the IMAP username and password unless you also pass --smtp-user and --smtp-pass.
The first account you add becomes the current one.
config accounts and config profiles are the same command.

On success fob-email signs in once to check the password, and prints the address it signed in as:

Saved account 'personal' to the fob-email config (mode 0600).
Verified — authenticates as [email protected] (gmail, threads: thread-id).

If the check fails you see (could not verify 'personal': …) instead. The account is still saved, so fix the problem (Troubleshooting) and run the same add command again: it replaces the saved account. --no-verify skips the check entirely.

Keep the password out of your shell history#

--imap-pass on the command line ends up in your shell history. To avoid that, read the password into a variable first:

read -rs IMAP_PASS        # paste the app password, press Enter; nothing is shown
fob-email config accounts add personal \
  --imap-host imap.gmail.com --imap-user [email protected] \
  --imap-pass "$IMAP_PASS" --smtp-host smtp.gmail.com
unset IMAP_PASS

3. Check it works#

fob-email config accounts list     # your account, * marks the current one
fob-email folders list             # proves sign-in works
fob-email emails list --limit 10   # your ten newest messages

If folders list shows your folders, you're connected.

Setting up with an AI agent?

Tell the agent to run fob-email getting-started. It prints these steps when no account exists, says setup is done when one does, and tells agents to ask you for the app password rather than make one up. See Use with AI agents.

Where your password is stored#

The CLI keeps accounts in ~/.fob/fob-email/config.yml. The file is written with mode 0600, so only your user can read it, but the password inside is plain text. To use a different folder, set FOB_EMAIL_CONFIG_DIR.

For workers, CI and containers, put accounts in the FOB_EMAIL_ACCOUNTS environment variable instead. See Accounts.

To stop fob-email reaching a mailbox, revoke its app password at your provider. Then remove the account locally with fob-email config accounts remove <name>.