# Add a domain to Mail Hosting

> Add your domain to a Mail Hosting service, publish its DNS records and verify it so its mailboxes can send and receive mail.

Source: https://www.coritan.com/docs/mail/mail-hosting/add-a-domain/

In the dashboard:

- /dashboard/mail/…/domains: https://www.coritan.com/dashboard/mail

Add the domain your addresses will be on, such as `example.com`, publish its DNS records and verify it. Once it is verified, it receives mail here and you can create mailboxes and aliases on it.

## Before you begin

- A Mail Hosting service with the status `active`. [Order one](/docs/mail/order-a-mail-service/) if you have none. While a service is being set up, **Add domain…** is greyed out.
- A domain whose DNS you can change. When its zone is on [Coritan DNS](/docs/websites/add-an-existing-domain/) in the same account, we publish the records for you.
- Room on the plan. The **Domains** card shows how many domains the plan allows, such as `1 of 1 on this plan.`
- A domain that is on no other mail service. A domain can be on one mail service at a time.

> [!IMPORTANT]
> Verifying a Mail Hosting domain needs its MX records to point here, and new mail follows the MX records straight away. If the domain receives mail somewhere else today, read [Move a domain that already receives mail](#move-a-domain-that-already-receives-mail) first.

## Add the domain

1. In the dashboard, go to [**Email**](https://www.coritan.com/dashboard/mail), open the Mail Hosting service, then the **Domains** tab.
2. Select **Add domain…**.
3. In **Domain**, enter the domain, such as `example.com`. Names you claimed under [coritan.gg](/docs/proxies/coritan-gg-names/) are listed beside **Your names:**; select one to fill it in.
4. Leave **Make this the primary domain** ticked if this is the service's main domain. The primary domain names the service in lists. The box starts ticked when the service has no primary domain yet.
5. Select **Add domain**.

The domain's page opens, with its records on the **DNS records** card.

## Publish the records

What you do depends on where the domain's DNS is:

- On Coritan DNS, in this account: nothing. We have already written the records into the zone, and the card reads *We publish these into your hosted zone and keep them up to date.* A record your zone already had wins over ours; see [Records we publish for you](/docs/mail/dns-records/#records-we-publish-for-you).
- On Coritan DNS, but added to this account after the domain: use the [**Publish to your zone**](/docs/mail/dns-records/#publish-to-your-zone) card on the domain's page.
- A claimed coritan.gg name: nothing. We publish its records and check the domain as soon as you add it.
- Anywhere else: create the records at your DNS provider, as the steps below describe.

To publish the records at another DNS provider:

1. Create the ownership record first: the TXT record at `_mailverify.example.com`. Copy its name and value from the **DNS records** card.
2. Create the MX, SPF and DMARC records and the rest of the list.
3. On the domain's page, select **Verify now**. Once we find the ownership record, we make the domain's two DKIM keys.
4. Reload the page. The card now lists the two DKIM records.
5. Create the two DKIM records.

[Mail DNS records](/docs/mail/dns-records/) explains every record and what its check looks for.

## Verify the domain

1. On the domain's page, select **Verify now**.
2. Read the toast. `example.com is verified.` means you are done. `example.com is still pending:` is followed by the first problem the check found.
3. If it is still pending, fix what the **Checks** row and the **The last check found problems** list show, and select **Verify now** again.

We also check pending domains about every ten minutes, so a domain whose records are right verifies on its own. The card's **Status** column shows each record's result from the last check.

## Result

- The domain shows `Verified` on the **Domains** tab, and **Ownership**, **MX**, **SPF** and **DKIM** are ticked. **DMARC** is shown too, but a domain is verified without it.
- The domain is offered in the **Mailboxes** and **Aliases** forms. See [Create and manage mailboxes](/docs/mail/mail-hosting/mailboxes/).
- Mail to addresses on the domain arrives here.
- When we publish into your zone, the page shows *Ready: the records are in your zone*, with **Create your first mailbox** (or **Create mailbox** once the service has mailboxes).

## Move a domain that already receives mail

The dashboard creates mailboxes only on a verified domain, and a domain verifies only once its MX records point here. To have the mailboxes ready before mail arrives, create them with the API instead: it accepts a domain as soon as its ownership record is found.

1. Add the domain as above.
2. Publish the ownership record, and add `include:_spf.<base>` from the card to your current SPF record, so the domain keeps one SPF record. Leave your MX records as they are.
3. Select **Verify now**. The ownership check passes; the domain stays pending because of MX.
4. Reload the page, then publish the two DKIM records it now lists.
5. Create the mailboxes with the API. See [Create and manage mailboxes](/docs/mail/mail-hosting/mailboxes/#with-the-api).
6. Copy the old mail in if you want to. See [Move existing mail into a mailbox](/docs/mail/mail-hosting/move-mail-in/).
7. Replace your MX records with the ones on the **DNS records** card, and publish the rest of the list.
8. Select **Verify now**.

Mail other servers already queued for the old MX hosts can still arrive there for a while after the change, so check the old mailboxes for a few days. Once you no longer send through the old provider, remove its include from your SPF record.

## Remove a domain

> [!WARNING]
> Removing a domain stops mail to and from it at once. If you add it again later, it gets a new ownership token and new DKIM keys, so you publish and verify it from the start.

1. Delete the mailboxes and aliases on the domain first. See [Delete a mailbox](/docs/mail/mail-hosting/mailboxes/#delete-a-mailbox) and [Forward addresses with aliases](/docs/mail/mail-hosting/aliases/).
2. On the **Domains** tab, select the domain.
3. In the **Remove this domain** card, select **Remove domain…**.
4. Type the domain name to confirm, then select **Remove domain**.

The **Settings** tab has the same **Remove domain…** button for each domain, under **Danger zone**. We delete the records we published into a hosted zone. Records at another DNS provider are yours to delete.

## Troubleshooting

**Add domain…** is greyed out
: The service is not `active` yet, or the plan's domains are all used. A full plan shows `This plan allows 1 domain. Remove one or change the plan to add another.` Remove a domain or [move to a bigger plan](/docs/mail/billing/#move-to-a-bigger-or-smaller-plan).

`Enter a domain, such as example.com.`
: The **Domain** field is empty or is not a domain name. Enter the name alone, without `https://` or an address.

`Enter a valid domain name such as example.com`
: The API refused the name. Use letters, digits and hyphens in each label, and a real top-level domain.

`Wildcard domains cannot receive mail`
: Enter a name such as `example.com` rather than `*.example.com`.

`That domain is already attached to a mail service`
: Someone else's mail service has it. If the domain is yours, contact [support](/docs/support/conversations/).

`example.com is a sending domain on your SMTP Relay service. To host mailboxes on it, remove it there and give the relay a sending subdomain such as send.example.com.`
: A domain can be on one mail service. [Add a sending subdomain](/docs/mail/smtp-relay/add-a-sending-domain/) to the relay, remove the domain from the relay, then add it here. The relay can still send as `@example.com`.

`example.com is already on another of your mail services`
: Remove it from the other Mail Hosting service first.

`example.com is a name the mail platform uses itself` or `example.com is one of the platform's own domains, so it cannot be added to this service`
: The name belongs to Coritan. Use a domain of your own.

`Claim a coritan.gg name before using alex.coritan.gg; it is not yours yet`
: [Claim the name](/docs/proxies/coritan-gg-names/) first. `coritan.gg is the platform's own domain; claim a name under it first` means you entered `coritan.gg` itself.

`This plan allows 1 domain(s)`
: The plan is full. Remove a domain or [move to a bigger plan](/docs/mail/billing/#move-to-a-bigger-or-smaller-plan).

`MX points to` followed by other hosts
: The domain's MX records still name another provider. Replace them with the ones on the **DNS records** card. When we publish into your zone, we add no MX records while another provider's are there, so delete those yourself.

`DKIM selector cor202609r not published`
: The DKIM record with that selector is missing or holds a different key. Copy the whole value again; some DNS providers split long TXT values, which is fine as long as nothing is lost.

`No DKIM keys yet: the mail engine has not made them`
: We have not finished making the domain's keys. Select **Verify now** again in a minute.

`DMARC publishes p=none, expected p=quarantine`
: Your DMARC record has a different stage from the one we expect. The domain verifies without DMARC; see [DMARC](/docs/mail/dmarc/) to fix it.

`The zone is busy with another change. Check the domain again in a minute.`
: Another change to the same zone was being saved. Select **Verify now** again.

`Remove the mailboxes and aliases on this domain first`
: Delete them, then remove the domain.

**Sending only**
: An older domain that passed its checks before MX was required. Its MX records point elsewhere, so it sends but does not receive mail here. Publish the MX records on the card to receive mail.

## Related

- [Mail DNS records](/docs/mail/dns-records/)
- [Create and manage mailboxes](/docs/mail/mail-hosting/mailboxes/)
- [How the DMARC stage ramp works](/docs/mail/dmarc/)
- [Mail troubleshooting](/docs/mail/troubleshooting/)

## With the API

Add a domain:

```bash
curl -X POST https://api.coritan.com/api/v1/client/mail/4812/domains \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com", "primary": true}'
```

`domain` is the name (3–253 characters) and `primary` defaults to `false`. The answer is `201` with the domain and its `records`, in the shape [the records endpoint](/docs/mail/dns-records/#with-the-api) returns. A name the service refuses answers `400` with one of the messages in [Troubleshooting](#troubleshooting). The coritan.gg claim messages answer `403`, and a service that is not active answers `409` `Service is not active`.

Check the domain now:

```bash
curl -X POST https://api.coritan.com/api/v1/client/mail/4812/domains/311/verify \
  -H "Authorization: Bearer $CORITAN_TOKEN"
```

```json
{
  "domain": { "id": 311, "domain": "example.com", "status": "pending", "checks": { "ownership": true, "mx": false, "spf": true, "dkim": true, "dmarc": true } },
  "result": {
    "ownership": true,
    "mx": false,
    "spf": true,
    "dkim": true,
    "dmarc": true,
    "dmarc_policy": "none",
    "errors": ["MX points to aspmx.example.net"],
    "dkim_pending_published": []
  }
}
```

The other domain operations:

| Operation | What it does |
| --- | --- |
| `GET /client/mail/{service_id}/domains` | Lists the service's domains as `{"items": [...]}`, each with `status`, `checks`, `is_primary`, `dmarc_policy` and `last_error`. |
| `GET /client/mail/{service_id}/domains/{domain_id}/records` | The records to publish. See [Mail DNS records](/docs/mail/dns-records/#with-the-api). |
| `PATCH /client/mail/{service_id}/domains/{domain_id}/dmarc` | Sets or holds the DMARC stage. See [DMARC](/docs/mail/dmarc/#with-the-api). |
| `DELETE /client/mail/{service_id}/domains/{domain_id}` | Removes the domain and answers `{"ok": true}`. |

A domain that is not on the service answers `404` `Domain not found`.

## API

- `GET /api/v1/client/mail/{service_id}/domains`: List domains (https://www.coritan.com/docs/api/reference/client/mail/mail-domains/#op-get-api-v1-client-mail-service-id-domains)
- `POST /api/v1/client/mail/{service_id}/domains`: Add domain (https://www.coritan.com/docs/api/reference/client/mail/mail-domains/#op-post-api-v1-client-mail-service-id-domains)
- `DELETE /api/v1/client/mail/{service_id}/domains/{domain_id}`: Remove domain (https://www.coritan.com/docs/api/reference/client/mail/mail-domains/#op-delete-api-v1-client-mail-service-id-domains-domain-id)
- `PATCH /api/v1/client/mail/{service_id}/domains/{domain_id}/dmarc`: Set DMARC (https://www.coritan.com/docs/api/reference/client/mail/mail-domains/#op-patch-api-v1-client-mail-service-id-domains-domain-id-dmarc)
- `GET /api/v1/client/mail/{service_id}/domains/{domain_id}/records`: Domain records (https://www.coritan.com/docs/api/reference/client/mail/mail-domains/#op-get-api-v1-client-mail-service-id-domains-domain-id-records)
- `POST /api/v1/client/mail/{service_id}/domains/{domain_id}/verify`: Verify domain (https://www.coritan.com/docs/api/reference/client/mail/mail-domains/#op-post-api-v1-client-mail-service-id-domains-domain-id-verify)