Secure a mailbox

Each mailbox on a Mail Hosting service has three controls that decide who can sign in to it: app passwords for mail apps, two-factor sign-in with an authenticator app, and the list of browsers signed in to webmail. You reach all three from the mailbox's menu on the Mailboxes tab. The mailbox's own user can manage the same things in webmail; see Protect your webmail mailbox.

• A mailbox on a Mail Hosting service. See Create and manage mailboxes.
• For two-factor sign-in, an authenticator app on a phone or computer. Any app that reads an otpauth:// link or takes a key by hand works.

An app password signs one mail app in to the mailbox in place of its password, and skips the two-factor code. Give each app its own, so you can revoke one without touching the others.

1. In the dashboard, go to Email, open the Mail Hosting service, then the Mailboxes tab.
2. Open the menu at the end of the mailbox's row and select App passwords….
3. Optionally, enter a Label that names the app or device, such as phone. It can be up to 64 characters.
4. Select Create app password.
5. Copy the App password from the dialog that opens. We show it once and cannot show it again.

In the mail app, use the mailbox's address as the username and the app password as the password. The mailbox's Security column counts its app passwords, such as 2 app passwords.

A mailbox holds at most ten app passwords. Each browser signed in to webmail uses one of them, so the more browsers are signed in, the fewer you can create.

1. On the Mailboxes tab, open the menu at the end of the mailbox's row and select App passwords….
2. Find the password by its label. Each row also shows the date it was created.
3. Select Revoke…, then Revoke app password.

The app that used it can no longer sign in. The list also shows the passwords the mailbox's user made in webmail for their devices, and revoking one here signs that device out too.

With two-factor sign-in on, webmail asks for a six-digit code from an authenticator app after the password.

1. On the Mailboxes tab, open the menu at the end of the mailbox's row.
2. Select Turn on two-factor sign-in.
3. From the dialog that opens, add the mailbox to the authenticator app: open the otpauth URI on the device with the app, or type the Secret into it. We show them once. The app lists the mailbox under the service's mail server name, such as mail-fra.coritan.com.

The Security column changes to Two-factor on, and every browser signed in to webmail is signed out. The next time someone signs in, webmail shows Enter your code after the password and takes the code in Code. Codes change every 30 seconds.

Mail apps cannot ask for a code. A mail app that signed in with the mailbox's password stops working until you give it an app password. App passwords made before you turned two-factor sign-in on keep working.

To turn off two-factor sign-in from the dashboard, give the mailbox a new generated password:

1. On the Mailboxes tab, open the menu at the end of the mailbox's row.
2. Select Reset password….
3. Choose Generate a strong password, then select Reset password.
4. Copy the new password from the dialog and give it to the mailbox's user.

The mailbox goes back to signing in with the password alone. Reload the page to see Two-factor off in the Security column. Resetting the password also signs the mailbox out of webmail everywhere; its app passwords keep working.

The mailbox's user can turn it off without a new password. In webmail, signed in with the mailbox's address, they turn off Ask for a code when signing in on the Security tab of settings and confirm with the mailbox's password. Turn off two-factor authentication explains what changes when they open the mailbox through a Coritan account instead.

A webmail session is one browser signed in to webmail as the mailbox. End one when a device is lost, or when someone should no longer read the mailbox.

1. On the Mailboxes tab, open the menu at the end of the mailbox's row and select Webmail sessions….
2. Read the list. Each row names the browser and system, such as Firefox on Windows, then the IP address, when it was last used and when it started. Hover over the name to see the browser's full description.
3. To sign out one browser, select End session… on its row, then End session.
4. To sign out every browser, select Sign out everywhere…, then Sign out everywhere.

The browser has to sign in again with the mailbox's address and password. Ending sessions does not change the password, so anyone who knows it can sign in again: to lock someone out, reset the password as well. Mail apps keep working, because they use the password or an app password rather than a session.

A session also ends by itself:

• after 30 days, or after 7 days without use;
• when a sixth browser signs in to the mailbox, which ends the one used longest ago;
• when you reset the password, turn two-factor sign-in on or off, or turn the mailbox off or delete it.

Turning two-factor login off needs the mailbox password; reset the password to clear it instead

Turn off two-factor sign-in… cannot work from the dashboard. Reset the password with a generated one, or ask the mailbox's user to turn it off in webmail.

A mail app stopped signing in after two-factor sign-in went on

The app signs in with the mailbox's password, which now needs a code the app cannot send. Create an app password and enter it in the app in place of the password.

Mail engine error: AppPassword not created

The mail server refused to make the password. The mailbox may already hold ten app passwords, counting one for each browser signed in to webmail. Revoke one you no longer use, or end a webmail session, then try again.

Mailbox is not registered in the engine yet

The mailbox was created moments ago and its setup has not finished. Wait a minute, then try again.

A browser keeps being signed out of webmail

A mailbox keeps at most five webmail sessions, so signing in on a sixth browser ends the one used longest ago. A password reset, a two-factor change and turning the mailbox off end every session.

No one is signed in to the webmail

No browser holds a session for the mailbox. Mail apps never appear in this list.

• Create and manage mailboxes
• Connect a mail app to Mail Hosting
• Protect your webmail mailbox

All the paths below sit under /client/mail/{service_id}/mailboxes/{account_id}, where account_id is the mailbox's id from GET /client/mail/{service_id}/mailboxes.

Create an app password:

curl -X POST https://api.coritan.com/api/v1/client/mail/4812/mailboxes/5120/app-passwords \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"label": "phone"}'

label is 1–64 characters and defaults to app password. The answer is 201, and secret is the password, returned this once:

{
  "id": 5120,
  "address": "alex@example.com",
  "credential_id": "b7",
  "label": "phone",
  "secret": "k3Vd9QxT2mLw7RpZ"
}

Turn on two-factor sign-in:

curl -X POST https://api.coritan.com/api/v1/client/mail/4812/mailboxes/5120/totp \
  -H "Authorization: Bearer $CORITAN_TOKEN"

The answer carries the secret and the otpauth_uri once. The URI names SHA-1, six digits and a 30-second period, and its issuer is the service's mail server name:

{
  "id": 5120,
  "address": "alex@example.com",
  "otpauth_uri": "otpauth://totp/mail-fra.coritan.com%3Aalex%40example.com?secret=JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP&issuer=mail-fra.coritan.com&algorithm=SHA1&digits=6&period=30",
  "secret": "JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP"
}

The other operations:

Each session in GET .../sessions has these fields:

id

The session's id, for DELETE .../sessions/{session_id}.

created_at, last_used_at

When it signed in and when it was last used, in UTC.

expires_at

When it ends if nobody uses it from now on: 7 days after last_used_at, and never more than 30 days after created_at.

ip, user_agent

The IP address and the browser's own description of itself.

An account_id that is not a mailbox on the service answers 404 Not found, and a failure on our side answers 502 with a message that starts Mail engine error:.