Connecting mail apps

This page is for anyone setting up an app against a Nixt Server account. The examples use alex@example.com as the address and mail.example.com as the server; your administrator can tell you your server’s name.

Settings at a glance

• Choose “normal password” (sometimes called “password, transmitted insecurely”, which is safe here because the connection is encrypted) as the authentication method. SCRAM-SHA-256 also works where the app offers it.
• Prefer the SSL/TLS ports. The STARTTLS ports refuse your password until the connection is encrypted.
• Your administrator may have moved a service to another port; automatic setup always gives the ports the server really listens on.

Automatic setup

Most apps only need your email address and password. The server publishes the rest in three ways.

SRV records

Apps that follow RFC 6186 look up _imaps._tcp, _imap._tcp, _pop3s._tcp, _pop3._tcp, _submissions._tcp and _submission._tcp in your domain’s DNS. Nixt Mail also looks up _jmap._tcp. Your administrator publishes these; see DNS records.

Autoconfig (Thunderbird and others)

The server answers Mozilla autoconfig at:

• https://autoconfig.example.com/mail/config-v1.1.xml
• https://autoconfig.example.com/.well-known/autoconfig/mail/config-v1.1.xml

The document lists IMAP first, then POP3, then outgoing SMTP, each with its host, port and security, %EMAILADDRESS% as the user name, and a normal password as the authentication method. For POP3 it suggests leaving messages on the server, because the same mail is usually read on other devices too. When ManageSieve is available, its host and port are noted in a comment. When the server also runs calendars and contacts, the document names the CalDAV and CardDAV server beside the mail servers, with your address as the user name, so Thunderbird adds your calendars and address books along with your mail.

Implicit TLS is offered wherever the node runs it (993, 995 and 465); the STARTTLS ports are offered only when those are all there is.

Autodiscover (Outlook)

Outlook posts a request naming your address to:

• https://autodiscover.example.com/autodiscover/autodiscover.xml
• https://autodiscover.example.com/Autodiscover/Autodiscover.xml

The answer lists IMAP, POP3 and SMTP with your address as the login name, SSL encryption for the TLS ports and TLS for STARTTLS ports.

When automatic setup does not answer

The autoconfig and autodiscover names must point at the server in DNS; see DNS records.

An app password, and an iPhone or Mac profile

Where your organisation asks for a second step when you sign in, mail apps that connect over IMAP, POP3, SMTP, ManageSieve, CalDAV or CardDAV cannot ask for it, and your own password no longer opens them. Make an app password for each such app instead, on your mail server’s own page:

1. Open https://mail.example.com/account/app-passwords and sign in with your address and password, and your second step if you are asked for one.
2. Name the app or device, tick what it may do — read mail, send mail, calendars and contacts — and choose Make it.
3. The password is shown once, in groups of four, beside your user name and the servers and ports to enter. Type or paste it into the app’s password field.

The same page lists the app passwords you have made, when each was last used, and revokes any of them. The page keeps you signed in for fifteen minutes.

On an iPhone, iPad or Mac, the page also offers a configuration profile that sets up the Mail app, and your calendars and contacts where the server serves them, in one step. In Safari on the device, choose Install on this device; on a computer, point the phone’s camera at the code shown, within fifteen minutes. Then open Settings › Profile Downloaded, choose Install, and paste your app password when asked. The profile holds no password, and it is signed by your mail server, so the device shows it as verified when the server’s certificate is from a public authority.

Nixt Mail

Nixt Mail connects to Nixt Server over JMAP, signing in on the server’s own page so that the app never sees your password, or over IMAP and SMTP with your password.

Over JMAP

1. In Nixt Mail, add an account and choose IMAP / SMTP (Any other provider).
2. Enter your email address. If your domain publishes a _jmap._tcp record, the app switches to JMAP and fills in the server for you. Otherwise choose Sign in with JMAP instead.
3. Check Email and JMAP server (mail.example.com), then choose Sign in with mail.example.com.
4. Your browser opens the server’s Sign in page. Enter your Email address and Password and choose Approve.
5. Return to Nixt Mail. Where no browser can be opened, the app shows a code and Open the sign-in page instead; see Approve a device.

Over IMAP and SMTP

Use the settings at the top of this page. To go back from the JMAP form, choose Use a password over IMAP instead.

A self-signed certificate

If the server uses a certificate your computer does not trust, Nixt Mail shows its SHA-256 fingerprint and asks. Compare it with the fingerprint your administrator gave you, then choose Trust and connect. See Accounts in the Nixt Mail documentation.

IMAP

• Folders. Every account has Inbox, Drafts, Sent, Junk, Trash and Archive, marked with their special uses so apps find them whatever language they display. You can create, rename and delete your own folders; the six standard folders cannot be deleted.
• Sent mail. Apps that send over SMTP save their own copy to Sent.
• New mail. IDLE tells your app about new mail as it arrives. A connection may stay silent for up to 31 minutes.
• Several devices. IMAP and JMAP read the same mailboxes, so a message read, flagged or moved in one app shows the same everywhere.
• Other people’s mail. If somebody has made you a delegate who may read their mail, their folders are under Other Users/ followed by their address. You can read and search them, but not change anything in them.
• Limits. At most 30 connections from one address.

Protocols and limits lists every IMAP extension the server offers.

POP3

• POP3 sees only your Inbox.
• The list of messages is fixed when you sign in: message numbers do not change during a session, and mail that arrives meanwhile appears next time.
• UIDL gives each message an identifier that stays the same across sessions and is never reused.
• Messages you delete with DELE are removed only when your app ends the session with QUIT. If the connection drops first, nothing is removed.
• Two sessions can be open at the same time; the server does not lock the mailbox.
• A connection may stay silent for up to 15 minutes.

Leaving messages on the server is the better choice if you also read mail in another app.

Outgoing mail (SMTP submission)

• Sign in before sending. Every address in the From header, the Sender header if there is one, and the envelope sender must be one of your own addresses, the address of a group you belong to, or an address your administrator has let you send as. Otherwise the message is refused with 550 5.7.1 The From header is not an address you may send as or 550 5.7.1 Not an address you may send as.
• A message has one From header, which may name up to 100 authors, and at most one Sender header, naming one address.
• To send on somebody’s behalf, put their address in From and one of your own in Sender. This works if they have made you a delegate who may send on their behalf.
• The server adds Message-ID and Date if your app leaves them out, and signs the message with your domain’s DKIM keys.
• A message may be up to 25 MiB (less if your administrator has lowered the limit) and have up to 100 recipients.
• Apps can send a message already in a mailbox without uploading it again, using BURL.

See Sending and delivery for what happens next.

JMAP

JMAP is a modern protocol that carries mail, sending, identities and out-of-office replies over HTTPS, with push notifications.

Every request needs an OAuth access token in an Authorization: Bearer header; see Signing in. The session names your account, your address and the capabilities the server offers: core, mail, submission, vacation response and WebSocket.

• Identities. Your identities are your addresses. You can change an identity’s name, signatures, reply-to and bcc.
• Sending. A message is sent from a draft with EmailSubmission/set, and the app can file it into Sent in the same request.
• Out of office. VacationResponse sets an automatic reply; see Sieve filters and vacation replies.
• Push. Changes arrive over EventSource or WebSocket.
• Other people’s mail. If somebody has made you a delegate who may read their mail, the session holds their account beside yours, marked read-only. Its mail can be read and searched, and a request that would change it is refused with accountReadOnly.

Protocols and limits lists every method and limit.

ManageSieve

Apps and add-ons that edit Sieve filters connect to port 4190, start TLS with STARTTLS, and sign in with your address and password. You can keep up to 32 scripts, with one active at a time. See Sieve filters and vacation replies.

Calendars and contacts

CalDAV and CardDAV are served on port 443 when the dav role runs.

1. In your calendar or contacts app, add a CalDAV or CardDAV account.
2. For the server, enter mail.example.com or https://mail.example.com/. The app finds the service through /.well-known/caldav or /.well-known/carddav, which redirect to /dav/. If your app wants the full address, use https://mail.example.com/dav/.
3. Enter your email address and password.

The app then finds your own calendar home at /dav/calendars/<id>/ and address book home at /dav/addressbooks/<id>/, where <id> is your tenant and account numbers joined by a hyphen, such as 1-2.

• A new account has no calendars or address books. Your app creates the first one when you add it.
• Formats. Events and tasks in iCalendar; contacts in vCard 4 or vCard 3, kept in the version your app sent.
• Synchronisation. Apps fetch only what changed since they last looked.
• Recurring events. Expanded up to 5,000 instances per request, over a range of at most ten years, between 1901 and 2100.
• Limits. Up to 200 calendars and 200 address books, up to 100,000 items and 64 MiB in each, and 10 MiB for one item.

A changed password keeps working in a calendar app for up to 30 seconds, because the server briefly remembers a successful sign-in.