Connecting a custom IMAP account: what to have ready first

Custom IMAP setups fail for the same handful of reasons almost every time: a missing port number, a password that should have been an app password, or a security setting typed as the wrong value. None of these are hard to fix once you know what to look for. Gather the five pieces below before you start and the connection should work on the first try.

What "custom IMAP" means here

Gmail, Outlook, and iCloud all connect through their own OAuth flow in STAMP, no manual server details needed. Custom IMAP is what you use for everything else: Fastmail, a self-hosted mail server, a domain email through your web host, Proton Bridge, or any provider that doesn't offer OAuth.

The checklist

Have these five things ready before you click "Add Account" → "Other (IMAP)":

1. Incoming (IMAP) server hostname. Something like imap.fastmail.com or mail.yourdomain.com. Your provider's help pages will list this under "IMAP settings" or "mail client setup."
2. Incoming port number. Almost always 993 for IMAP over SSL. If your provider gives you a different number, use theirs, not 993 by default.
3. Outgoing (SMTP) server hostname and port. Often a different hostname than IMAP, commonly smtp.yourprovider.com on port 465 or 587. Get this wrong and mail will arrive fine but you won't be able to send.
4. SSL/TLS setting. Almost every modern provider requires SSL on both IMAP and SMTP. Leave it on unless your provider explicitly says otherwise. An SSL mismatch is the single most common reason a connection times out instead of failing with a clear error.
5. An app-specific password, if your provider requires one. This is the step people skip. If your account has two-factor authentication enabled (it should), your regular login password will not work for IMAP. You need a separate app password generated specifically for mail clients.

How to generate an app password

The exact menu differs by provider, but the pattern is the same everywhere:

1. Log into your provider's web settings (not STAMP).
2. Find "Security," "App Passwords," or "Connected Apps."
3. Generate a new app password and label it something you'll recognize later, "STAMP" works fine.
4. Copy the generated password immediately. Most providers show it only once.
5. Paste that password into STAMP's account setup, not your normal login password.

Fastmail, Proton Bridge, and most self-hosted setups all use this pattern. If your provider has no two-factor authentication at all, your regular password may work, but turn on two-factor and switch to an app password anyway. It is safer and most providers are moving toward requiring it.

Adding the account in STAMP

1. Open STAMP, click "Add Account," and choose "Other (IMAP)."
2. Enter your email address and the app password from the step above.
3. Enter the IMAP hostname and port.
4. Enter the SMTP hostname and port.
5. Confirm SSL/TLS is enabled for both.
6. Click connect. STAMP will test both the incoming and outgoing connection before finishing setup and tell you specifically which one failed if something is wrong.

Common pitfalls

• Using your account password instead of an app password. This produces an authentication error that looks identical to a typo. Always check this first.
• Mixing up IMAP and SMTP hostnames. They are frequently different subdomains. Copy them separately, don't assume they're the same with a different port.
• Wrong port for the security setting. Port 587 usually pairs with STARTTLS, port 465 with SSL from the start. If sending fails but receiving works, this is the usual cause.
• Firewall or VPN interference. Corporate VPNs sometimes block non-standard mail ports. If a connection that should work times out, try without the VPN once to isolate the cause.
• Provider-side IMAP being disabled by default. Some providers ship with IMAP access off until you turn it on in settings. Check this before assuming the details are wrong.

Where credentials actually live

Once connected, your password (app-specific or otherwise) is stored in the macOS Keychain, the same secure system store Apple's own apps use. It is not stored in a STAMP database on our servers and it is not visible in plain text anywhere on disk.

If you run into a connection that won't resolve after checking all five items above, email us the provider name and the exact error text and we'll help track it down.

Any provider, one inbox. hello@stamp.email