# Your email addresses

Source: https://codeherder.com/docs/email-addresses/

Add verified secondary email addresses to your account, make one primary, and remove one. Use the web app or ch me emails.

Your account has one **primary** email address and can hold up to 20 **verified secondary** addresses. Secondary addresses matter most when your company uses [single sign-on](https://codeherder.com/docs/sso/). Your identity provider may send a different address from the one you first signed up with. A verified secondary address lets that sign-in find your existing account, so you keep one account.

An address belongs to one account only. Nobody else can hold an address that you hold, as a primary or as a secondary.

## What each kind does

- **Primary.** This is the address CodeHerder mails. Only the primary address gets mail.
- **Secondary.** This address does not get mail. An SSO connection that has verified the address’s domain can use it to recognise you. See [Single sign-on](https://codeherder.com/docs/sso/#who-can-sign-in-through-your-connection).
- **Pending.** This is an address you started to add and have not confirmed. It claims nothing until you enter its code.

A secondary address helps only with SSO, and only when the connection has verified the address’s domain. A password or Google sign-in does not accept a secondary address.

## Find your addresses

You manage addresses on your own **Profile** page. Open the user menu in the top bar and click **Profile**. It works from every page. The **Email addresses** section lists each address with its kind and status. Only you see this section, on your own profile. Agents have no email addresses.

## Add a secondary address

1. Click **Add email**.
2. Type the address and submit.
3. Open the mail sent to that address. It holds a 6-digit code.
4. Enter the code and confirm. The address now shows as **Secondary** and **Verified**.

The code expires after 10 minutes. CodeHerder gives the same answer whether or not it sent a mail. If another account holds the address, no mail goes out, and the app does not tell you why.

A pending address shows **Address not shown** and the time it expires. To finish later, click **Enter code**. The app asks for the address again.

Each address gets one code per minute, and at most five codes a day. A pending address counts toward your 20.

From the CLI:

```
ch me emails list
ch me emails add jo@example.com
ch me emails confirm <pendingId> --code 123456 --email jo@example.com
```

`add` prints the pending id. `list` shows it too. Pass the address to `confirm` again, because CodeHerder keeps only a hash of it.

## Make a secondary address your primary

Click **Make primary** on a verified secondary address. From the CLI:

```
ch me emails make-primary jo@example.com
```

Your old primary becomes a verified secondary if it was verified. If it was not verified, CodeHerder drops it.

If your account has a verified SSO domain, the new primary must be on one of those domains. Otherwise CodeHerder refuses with “this account needs an email on one of its verified SSO domains”.

The **Email** field on your profile is read-only. To change your primary, add the new address, confirm it, then make it primary.

## Remove a secondary address

Open the **More** menu on the row and click **Remove**. From the CLI:

```
ch me emails remove jo@example.com --yes
```

Without `--yes`, the command asks you to confirm. An SSO sign-in that used the address stops working. You can add the address again with a new code.

You cannot remove your primary address. Make another address primary first.

## Troubleshooting

- **No code arrived.** Check your spam folder. Another account may hold the address. The code may have expired after 10 minutes. You may have asked for a code in the last minute or five times today. Wait, then add the address again.
- **“this account already holds the most secondary emails it can; remove one first”.** You reached the limit of 20. Pending addresses count. Remove one and try again.
- **“the primary email cannot be removed; make another address primary first”.** Make a different verified address primary, then remove this one.
- **“this account needs an email on one of its verified SSO domains”.** Your account has a verified SSO domain. Pick an address on that domain as your new primary.
- **A secondary address does not let you sign in.** It works only for an SSO sign-in through a connection that verified its domain. Ask your admin whether the domain is verified. See [Single sign-on](https://codeherder.com/docs/sso/#when-it-goes-wrong).
