IMAP and other providers
Connect Yahoo, iCloud, FastMail, GMX, Yandex, Proton Mail Bridge or any IMAP/SMTP server, and what each connection setting does.
Any provider that offers IMAP for reading and SMTP for sending works with Airpost. For the common ones you only enter your address and a password; Airpost fills in the servers. For everything else you can enter the settings yourself.
Providers with app passwords
Several providers want an app password instead of your normal password, especially when two-factor authentication is on. Create one in your provider’s settings, then paste it into Airpost.
| Provider | What you need |
|---|---|
| Yahoo | A unique app password (Yahoo instructions). |
| iCloud | A unique app password (Apple instructions). |
| FastMail | An app password of type IMAP (FastMail instructions). To also sync calendars and contacts, give it CalDAV and CardDAV access. |
| GMX | IMAP turned on in GMX (GMX instructions). |
| Yandex | IMAP turned on, possibly a linked phone number, and an app password if you use two-factor auth. |
Pick the provider on the Connect an email account screen and enter your Name, Email and Password. Airpost fills in the server settings.
If the password is rejected, Airpost reminds you that some providers require an app password. That is the most common reason a Yahoo or iCloud account fails to connect.
# The same from the CLI, reading the app password from a password manager
op read "op://Personal/iCloud app password/password" | \
airpost account add me@icloud.com --provider icloud --password-stdin
Any IMAP/SMTP server
Choose IMAP / SMTP
Pick IMAP / SMTP and enter your name, email address and password, then click Continue.
Check the server settings
Airpost tries to detect your settings (see how discovery works). Check or fill in the Incoming Mail (IMAP) and Outgoing Mail (SMTP) columns.
Connect
Click Connect Account. The engine logs in to both servers before it saves anything. If one fails, you see the server’s answer and can fix the setting.
Connection settings
Each column has these fields:
| Field | Notes |
|---|---|
| Server | The host name, for example imap.example.com. |
| Port | Pick a standard port or choose Custom to type one. Picking a standard port also sets the matching security. |
| Security | SSL / TLS, STARTTLS or None. |
| Allow insecure SSL | Accepts certificates that can’t be verified, such as self-signed ones. The connection is still encrypted, but not authenticated. Use only on servers you trust. |
| Username and Password | Usually your email address and password. |
Standard ports and the security they imply:
| Protocol | Port | Security |
|---|---|---|
| IMAP | 993 | SSL / TLS |
| IMAP | 143 | STARTTLS |
| SMTP | 465 | SSL / TLS |
| SMTP | 587 | STARTTLS |
| SMTP | 25 | STARTTLS |
Unencrypted connections
Discovery never chooses None. If you pick it yourself for a server that isn’t on your own machine, Airpost shows a Send password unencrypted checkbox that you must tick before it will connect. The consent is tied to that host name, so if you later change the server, you’re asked again. Connections to 127.0.0.1, localhost or ::1 don’t ask, because the traffic never leaves your computer.
The CLI doesn’t offer cleartext at all: --imap-security and --smtp-security accept only tls and starttls.
Custom Container Folder
The IMAP column also has Custom Container Folder: the parent folder for folders Airpost creates on the server, such as the one snoozed mail moves to. The default is Airpost. Change it if your server requires custom folders under a particular parent (Proton Mail Bridge uses Folders, which Airpost sets for you).
Change settings later
Open the account in Preferences > Accounts and click Update connection settings… to change the password, servers or ports. To change just the password from the CLI:
airpost account reauth me@example.com # asks on the terminal
printf '%s\n' "$NEW_PASS" | airpost account reauth me@example.com --password-stdin
The engine tests the new credentials before replacing the old ones.
Add a custom server from the CLI
airpost account add me@example.com --name "Ada Lovelace" \
--imap-host mail.example.com --imap-port 993 --imap-security tls \
--smtp-host mail.example.com --smtp-port 587 --smtp-security starttls
Any flag you leave out comes from discovery. --imap-username and --smtp-username set a login that differs from the address.
Proton Mail Bridge
Proton Mail works through Proton Mail Bridge, which runs on your computer and exposes a local IMAP and SMTP server. Start Bridge, copy the password it shows for your account (not your Proton password), then add the account with IMAP / SMTP. For proton.me, protonmail.com and protonmail.ch addresses Airpost fills in Bridge’s defaults:
| Setting | Value |
|---|---|
| IMAP | 127.0.0.1, port 1143, STARTTLS |
| SMTP | 127.0.0.1, port 1025, STARTTLS |
| Allow insecure SSL | On (Bridge uses a self-signed certificate) |
| Container folder | Folders |
Bridge must be running for Airpost to sync or send. If you changed Bridge’s ports, use the ones Bridge shows.
Servers Airpost adapts to
The engine identifies the server on every connection, from its greeting, capabilities and ID response, and adjusts for known quirks. You don’t configure any of this.
| Server | What changes |
|---|---|
| iCloud | QRESYNC is never enabled. |
| Yahoo | Search without a charset; Yahoo’s mod-sequence extension; copied message IDs re-verified because Yahoo reorders them. |
| Yandex | Abrupt disconnects during IDLE are treated as normal. |
| Courier | IDLE and NAMESPACE are assumed even when not advertised. |
| Dovecot | A BYE on a UIDVALIDITY change is expected. |
| Coremail / NetEase | ID is sent before selecting a folder; the C-prefixed tags are handled. |
| hMailServer, home.pl | An unreliable UIDNEXT is worked around. |
| Proton Mail Bridge | Its All Mail folder is skipped and duplicate folder entries are merged. |
| Gmail, Office 365 | See Gmail and Microsoft. |
On servers that allow custom IMAP keywords, Airpost can store labels as keywords. Servers that don’t (Exchange, for example) just use folders.
Calendars and contacts
Airpost finds CalDAV and CardDAV for IMAP accounts automatically where the provider offers them, through DNS SRV records or a built-in list. See Calendar and contacts.
Troubleshooting a connection
| Symptom | Likely cause |
|---|---|
| “Authentication failed” on Yahoo, iCloud, FastMail | An app password is required. |
| Timeout on connect | Wrong port, or a firewall blocking 993/465/587. |
| Certificate error | A self-signed or expired certificate. Fix the server, or tick Allow insecure SSL if you trust it. |
| Connects, but sending fails | SMTP needs a different username, port 465 instead of 587, or your provider blocks port 25. |
| Folders appear under an unexpected parent | Adjust Custom Container Folder. |
airpost logs me@example.com shows the engine’s log for the account, including the server’s own error text. More in Troubleshooting.