Configuring aerc accounts for ITProMail

aerc is a terminal mail client that reads its account definitions from accounts.conf. This guide adds an ITProMail account that uses implicit TLS for IMAP and SMTP, and gets the app password from a command at runtime. Nothing secret is written into the file.

Step 1: Create and store an app password

In the webmail, open Account, then Security, and create an app password labelled for this machine, such as "aerc workstation". Store it in your password manager or a pass store. This example uses pass with the path itpromail/jane@example.com, as in the mutt guide. The first line of the entry must be the app password.

Step 2: Write accounts.conf

Create or edit ~/.config/aerc/accounts.conf. Each account is a section in square brackets. Replace the example name and address with your own:

[ITProMail]
source = imaps://jane%40example.com@imap.itpromail.com:993
source-cred-cmd = pass show itpromail/jane@example.com
outgoing = smtps+plain://jane%40example.com@smtp.itpromail.com:465
outgoing-cred-cmd = pass show itpromail/jane@example.com
from = Jane Example <jane@example.com>
copy-to = Sent
default = INBOX

The source line uses imaps://, which means IMAP over implicit TLS on port 993. The outgoing line uses smtps+plain://, which means SMTP over implicit TLS on port 465 with the PLAIN authentication mechanism. The TLS session is established before any credentials are sent. The %40 is the encoded @ in the username.

The source-cred-cmd and outgoing-cred-cmd lines run the command and use its output as the password, so the password itself never appears in the file. The from, copy-to and default values must match the names the server uses for those folders.

Step 3: Tighten permissions

The file holds your username and the command that retrieves your password. It is not a secret on its own, but there is no reason for other users to read it. Restrict it to your account:

chmod 600 ~/.config/aerc/accounts.conf

Step 4: Start aerc and test

Run aerc. The account should connect and list your folders. Compose a message to an address you control and check that it arrives. Then confirm that a copy appears in the Sent folder both in aerc and in the webmail.

Using STARTTLS instead

If port 465 is blocked, use port 587 with the plain smtp+plain:// scheme in the outgoing line. Plain smtp:// negotiates STARTTLS on submission ports, and it is the connection mode to use when the server offers TLS on that port. Do not use the smtp+insecure scheme, which turns encryption off.

outgoing = smtp+plain://jane%40example.com@smtp.itpromail.com:587
outgoing-cred-cmd = pass show itpromail/jane@example.com

If authentication fails

Run the credential command on its own in a shell. If it prints nothing, or prints a value that is not the app password, aerc will fail to log in. If the command works and login still fails, check that the username in the URL is the full address with %40 in place of the @.

If you have several accounts, add one section per account. aerc selects the account by the section name when you start it, so choose names that are easy to tell apart.

For the full server reference, see IMAP and SMTP settings. For login problems in general, see troubleshooting login.