Connecting an account
This page explains how an account gets connected to email-mcp: how server settings are suggested from an email address, how an account is tested and saved, what the web portal and the commands share, and how an account is reconnected after a mail server refused its login. Read it before you change discovery, the connect flow, the decision about a pin, or the reconnect. A pin is the fingerprint of a certificate that the person chose to trust. A certificate is the signed proof of identity that a mail server shows. The connections that an account uses afterwards are on The mail backend.
No tool of the agent connects an account. The tool connect_account returns a
link to the page where the person does it. The person connects an account in the
web portal (the pages under /connect) or with the command account add or
import-env, and reconnects it in the web portal (the page
/accounts/{id}/reconnect) or with account reconnect. The commands
account test and doctor test accounts that exist. All of these call the same
use cases in service.
Finding the settings
Finder.Mail in internal/discovery/discovery.go suggests server
settings from an email address. It asks four sources at the same time, so a slow
source cannot use the time of the others. The result keeps the order of the
sources.
| Source | What it reads | What it suggests |
|---|---|---|
| The ISP (internet service provider) database of Thunderbird | https://autoconfig.thunderbird.net/v1.1/<domain> |
The servers in the file, with ssl or starttls only |
| The file of the domain | https://autoconfig.<domain>/mail/config-v1.1.xml |
The same, from the domain itself |
| DNS SRV records (DNS is the Domain Name System; an SRV record names the host and port of a service) | _imaps._tcp for IMAP, _submissions._tcp and then _submission._tcp for SMTP |
The hosts and ports in the records. _imap._tcp is not used, because it has no TLS from the first byte. |
| A guess from the MX record (the record that names the mail server of a domain) | The MX host with the lowest preference number | imap.<base> on port 993 with TLS, and smtp.<base> on port 587 with STARTTLS, where <base> is the registrable domain of the MX host (the domain that a person can register, such as example.co.uk) |
The package keeps three promises. It does not suggest an unencrypted connection.
It does not send the email address: only the domain goes into an HTTP (HyperText
Transfer Protocol) request or a DNS query. And it stays small (see “Limits”). A
source that fails gives nothing, and the others still count. Mail returns
discovery.ErrNotFound when no source gave a suggestion, and
discovery.ErrInvalidAddress for an address that it cannot use, before any
network use. A host name is accepted only as a plain DNS name with at least two
labels. A label is one part of a name between dots, such as imap, example
and com in imap.example.com. A name that ends in a number is refused. A few
names that are for this computer, a local network, tests or examples are
refused too.
The result is only a list of suggestions. The web portal shows it before it asks for a password, because an MX guess can name the host of a third party, such as a spam filter. The person chooses the servers that get the password. A test must pass before an account is saved. Use only the servers that your provider names.
Saving an account
Service.CreateIMAPAccount in internal/service/accounts.go
connects an IMAP and SMTP account for the tenant of the caller. In this order,
it:
- cleans the address and the settings (outer spaces go, host names and pins
become lower case, an empty user name becomes the address), and checks them
with
MailServer.Validateand the form of the host names and the pins; - refuses an address that the tenant has connected already. This saves a test that would send the password for nothing. The store checks again when it saves, because another process may connect the same address while the probe runs;
- tests the settings with the password (
imapsmtp.Probe) and refuses unless both the IMAP login and the SMTP login work; - makes the account with
account.NewIMAPAccount: level Send (4), both confirmations on, and the default limits; - seals the password with the key of the tenant and stores the account and the sealed password in one transaction, so a failure leaves nothing;
- writes the audit entry
account_connected, which holds the account id and no address.
Probe logs in to the IMAP server, authenticates to the SMTP server with
AUTH PLAIN, sends no message and opens no mailbox. A certificate that is not
accepted does not fail the probe: it is reported in IMAPCert or SMTPCert,
and the other server is still tested. So the person can pin both certificates
after one probe. The service then returns a *CertificateError. A failed login
or connection gives a *ConnectionTestError. Neither holds the password or the
text of a server.
The shared package
internal/connect/connect.go holds what the web portal and the
commands share, so the two use the same rules:
- the fixed texts for each error of the use cases and for a failed test
(
ErrorText,TestFailureText). The type of the error chooses the text, so the text of a mail server does not reach the person; - the decision about a pin (
CheckCertificate,CheckReconnect); CleanHost, which cleans a host name as the service tests it;PlainOnThisComputer, which says that a server on this computer is set to a plain connection. This needs the explicit consent of the person. The service refuses a plain connection to another host, and no consent allows it;GroupFingerprint, which writes a fingerprint in pairs, such asAB:CD:EF.
The only value from a server that a caller may show is the fingerprint of a
certificate. The web portal binds an offer to pin to a signed token that lasts
certOfferTTL, 10 minutes, in internal/web/accounts.go.
A refused login and the reconnect
When a call to the mail server fails with ErrAuthFailed, noteBackendError in
service marks the account needs_reauth. The same happens in the sender of
the outbox. The mark is written only while the credentials version of the
account is the one that the failing call read. A reconnect adds one to this
version, so a call from before a reconnect cannot undo it. The write runs even
when the context of the call has ended, with its own limit of 30 seconds
(endTimeout; the sender has statusTimeout). authorize then refuses the
next call with a *ReauthError, before it reaches the server.
The account works again after ProbeAccount passes (account test and doctor
call it) or after ReconnectIMAPAccount, in
internal/service/reconnect.go. A reconnect keeps the id, the
server settings, the levels, the queued messages and the activity of the
account. It tests the stored settings with the password that the person gave, or
the stored one when none is given. It saves that password and the pins that the
person decided, in one step, and marks the account connected. A server whose
certificate is not accepted fails at the handshake, so the password is not sent
to it. A change of the hosts, the ports or the security modes is not a
reconnect: the person removes the account and adds it again.
ReconnectPinChange decides what a reconnect may do with a pin: add it,
replace it, remove it, or nothing (PinChangeRefused). The table in The secure
dialer gives each case.
A decision of the person counts only for the server that shows a certificate
with the same fingerprint in this test. Before a replace or a removal, the
person sees the old fingerprint, the fingerprint of the certificate that the
server shows, and a warning. If the certificate changes again during the test,
the result is ErrCertificateDecisionStale, and nothing is saved.
Limits
| Name | Value | What it bounds |
|---|---|---|
defaultLookupTimeout, httpTimeout (discovery.go) |
10 seconds | All four sources together, and one HTTP request |
maxBodyBytes, maxRedirects (discovery.go) |
1 MiB, 3 | One HTTP response, and the redirects of one request. A MiB (mebibyte) is 1,048,576 bytes. |
maxServersPerSide, maxSuggestions (discovery.go) |
4, 10 | Servers from one source for each protocol, and the length of the result |
Related pages
- The mail backend
- Storage and secrets
- Connect your first account in the user manual
- Manage accounts in the user manual
- Troubleshooting in the user manual