# Internal mail tenants

> How the platform's own mail tenants appear on the owning account's dashboard, and what their owner and staff can each change.

Source: https://docs.coritan.com/mail/internal-tenants/

In the dashboard:

- /dashboard/mail/internal/…/overview: https://www.coritan.com/dashboard/mail/internal
- /dashboard/mail/internal/…/domains: https://www.coritan.com/dashboard/mail/internal
- /dashboard/mail/internal/…/mailboxes: https://www.coritan.com/dashboard/mail/internal
- /dashboard/mail/internal/…/aliases: https://www.coritan.com/dashboard/mail/internal
- /dashboard/mail/internal/…/settings: https://www.coritan.com/dashboard/mail/internal
- /dashboard/mail/internal/…/credentials: https://www.coritan.com/dashboard/mail/internal
- /dashboard/mail/internal/…/api-keys: https://www.coritan.com/dashboard/mail/internal
- /dashboard/mail/internal/…/webhooks: https://www.coritan.com/dashboard/mail/internal
- /dashboard/mail/internal/…/suppressions: https://www.coritan.com/dashboard/mail/internal
- /dashboard/mail/internal/…/events: https://www.coritan.com/dashboard/mail/internal
- /dashboard/mail/internal/…/send: https://www.coritan.com/dashboard/mail/internal

An *internal mail tenant* is a Mail Hosting or SMTP Relay setup that belongs to the platform itself, such as the relay that sends the platform's own emails or the team mailboxes on its own domains. The platform's seed file declares each one. An internal tenant has no order and no bill, so it is not a service.

Only the account that the platform's mail belongs to sees internal tenants. They appear on that account's **Email** page with its ordinary services. On any other account, a link to one opens the page-not-found screen.

## How an internal tenant appears

In the **Email** list, internal tenants come first. The line under each one's domain gives the tenant's name followed by `internal, no billing`. Select the row to open the tenant.

The tenant's page looks like a service's page, with these differences:

- The header shows an **Internal** badge beside the status and the product, and the tenant's number, such as `Tenant #12`, where a service shows its service number.
- A note below the header, **One of the platform's own tenants**, says that it has no order or bill, that staff set its limits, and that only staff can remove what the seed file declares.
- A Mail Hosting tenant has the tabs **Overview**, **Domains**, **Mailboxes**, **Aliases** and **Settings**. An SMTP Relay tenant has **Overview**, **Domains**, **Credentials**, **API keys**, **Webhooks**, **Suppressions**, **Events** and **Send**. Neither has a **Billing** tab.
- On the **Overview** tab, the **Tenant** card takes the place of the **Service** card. Its **Plan** reads `Internal, no billing`, it shows the **Tenant ID**, and it has no renewal date. The tab has no **Tags** card.
- An SMTP Relay tenant's **Overview** tab has no **Sending IPs** card. When the monthly allowance runs out, its warning says `We refuse further emails until the next month starts or staff raise the allowance.` and has no **Change plan** button.

**Open webmail** at the top of a Mail Hosting tenant opens webmail, as it does on a service. The **Sending is paused** and **Under review** notes appear on a tenant as they do on a service ([Sending reputation and deliverability](/mail/smtp-relay/deliverability/)).

## What the owner can change

The owning account uses each tab as it would on a service of the same kind, within the tenant's limits:

- Add domains, publish and verify their records, and set their DMARC stage ([Add a domain to Mail Hosting](/mail/mail-hosting/add-a-domain/), [Add a sending domain](/mail/smtp-relay/add-a-sending-domain/)).
- Create and manage mailboxes and aliases ([Create and manage mailboxes](/mail/mail-hosting/mailboxes/), [Forward addresses with aliases](/mail/mail-hosting/aliases/)).
- Create credentials and send API keys, add webhooks, manage the suppression list, look up events and send a test message ([How SMTP Relay works](/mail/smtp-relay/)).
- Set the tenant's default message category: on the **Settings** tab of a Mail Hosting tenant, and in the **Deliverability** card on the **Overview** tab of an SMTP Relay tenant ([Transactional and marketing mail](/mail/smtp-relay/message-categories/)).

A mailbox that the platform created for a tenant starts with a password that nobody has seen. Set one with **Reset password…** in the mailbox's menu on the **Mailboxes** tab before anyone signs in ([Reset a mailbox password](/mail/mail-hosting/mailboxes/#reset-a-mailbox-password)).

The seed file can also name a domain without adding it, so that the owning account decides when the domain's mail moves. Add it on the **Domains** tab when you are ready ([Move a domain that already receives mail](/mail/mail-hosting/add-a-domain/#move-a-domain-that-already-receives-mail)).

We record every change the owning account makes to an internal tenant, from the dashboard or through the API, in the platform's audit log.

## What only staff can change

Staff make these changes from the admin console:

A domain that the seed file declares
: Only staff can remove it. The domain's page on the **Domains** tab shows `The platform's seed file declares this domain, so only staff can remove it, from the admin console.` under **Remove this domain**, and greys out **Remove domain…**. The **Remove domain…** button in the **Danger zone** card on the **Settings** tab is not greyed out, but the removal fails with the same message. Once you add a domain that the seed file names, it is locked in the same way.

The credential the platform sends its own mail with
: On an SMTP Relay tenant, the credential's row on the **Credentials** tab shows `The platform sends its own mail with this credential. You can rotate it, but only staff can disable or delete it.` Its **Enabled** switch is greyed out, and **Revoke credential…** shows **Staff only**. **Rotate password…** works: the platform's own mail uses the new password from its next message ([Rotate a password](/mail/smtp-relay/credentials/#rotate-a-password)).

The tenant's limits
: Staff set how many domains, mailboxes and credentials a tenant may hold, the storage for each mailbox, the monthly allowance and the hourly limit. On the **Hourly limit** card, **Request limit increase…** is greyed out, with the note `Staff set the limits of an internal tenant, from the admin console.` The limits the seed file declares apply again each time the platform starts.

## With the API

The routes under `/api/v1/client/platform-mail/{tenant_id}` are the same as a mail service's under `/api/v1/client/mail/{service_id}` and `/api/v1/client/smtp-relay/{service_id}`. They take the tenant ID where a service's routes take the service ID, and each operation takes the same body and answers in the same shape as on a service. The pages linked above document each operation. As on a service, an operation that belongs to the other product answers with a message that says so, such as `Not an SMTP Relay service`.

There is no list under `platform-mail`. `GET /api/v1/client/mail/services` lists internal tenants first, each with `"internal": true`, `"service_id": null` and its `tenant_id` ([Email](/mail/#with-the-api)).

`GET /api/v1/client/platform-mail/{tenant_id}` returns the tenant's summary, as the summary of a [Mail Hosting](/mail/mail-hosting/#with-the-api) or [SMTP Relay](/mail/smtp-relay/#with-the-api) service does. `kind` is `hosting` or `relay`, `label` is the tenant's name and `service` is `null`.

Set the default message category with `PATCH /api/v1/client/platform-mail/{tenant_id}/category`:

```bash
curl -X PATCH https://api.coritan.com/api/v1/client/platform-mail/12/category \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"default_category": "marketing"}'
```

```json
{"default_category": "marketing"}
```

`default_category` is `transactional` or `marketing`, and any other value answers `422`.

In the answers to `GET /api/v1/client/platform-mail/{tenant_id}/domains` and `GET /api/v1/client/platform-mail/{tenant_id}/credentials`, each item carries `locked`. It holds the reason when only staff can remove the item, and `null` otherwise.

| Request | Status | `detail` |
| --- | --- | --- |
| `DELETE …/domains/{domain_id}` for a domain the seed file declares | `409` | `The platform's seed file declares this domain, so only staff can remove it, from the admin console.` |
| `PATCH …/credentials/{account_id}/enabled` with `"enabled": false`, or `DELETE …/credentials/{account_id}`, for the platform's sending credential | `409` | `The platform sends its own mail with this credential. You can rotate it, but only staff can disable or delete it.` |
| `POST …/limits/increase-request` | `409` | `Staff set the limits of an internal tenant, from the admin console.` |
| Any request with a tenant ID that is not an internal tenant of your account | `404` | `Mail service not found` |

## API

- `GET /api/v1/client/platform-mail/{tenant_id}`: Get summary (https://docs.coritan.com/api/reference/client/mail/platform-mail/#op-get-api-v1-client-platform-mail-tenant-id)
- `GET /api/v1/client/platform-mail/{tenant_id}/domains`: List domains (https://docs.coritan.com/api/reference/client/mail/platform-mail-domains/#op-get-api-v1-client-platform-mail-tenant-id-domains)
- `POST /api/v1/client/platform-mail/{tenant_id}/domains`: Add domain (https://docs.coritan.com/api/reference/client/mail/platform-mail-domains/#op-post-api-v1-client-platform-mail-tenant-id-domains)
- `DELETE /api/v1/client/platform-mail/{tenant_id}/domains/{domain_id}`: Remove domain (https://docs.coritan.com/api/reference/client/mail/platform-mail-domains/#op-delete-api-v1-client-platform-mail-tenant-id-domains-domain-id)
- `PATCH /api/v1/client/platform-mail/{tenant_id}/domains/{domain_id}/dmarc`: Set DMARC (https://docs.coritan.com/api/reference/client/mail/platform-mail-domains/#op-patch-api-v1-client-platform-mail-tenant-id-domains-domain-id-dmarc)
- `GET /api/v1/client/platform-mail/{tenant_id}/domains/{domain_id}/records`: Domain records (https://docs.coritan.com/api/reference/client/mail/platform-mail-domains/#op-get-api-v1-client-platform-mail-tenant-id-domains-domain-id-records)
- `POST /api/v1/client/platform-mail/{tenant_id}/domains/{domain_id}/verify`: Verify domain (https://docs.coritan.com/api/reference/client/mail/platform-mail-domains/#op-post-api-v1-client-platform-mail-tenant-id-domains-domain-id-verify)
- `PATCH /api/v1/client/platform-mail/{tenant_id}/category`: Set category (https://docs.coritan.com/api/reference/client/mail/platform-mail/#op-patch-api-v1-client-platform-mail-tenant-id-category)
- `GET /api/v1/client/platform-mail/{tenant_id}/mailboxes`: List mailboxes (https://docs.coritan.com/api/reference/client/mail/platform-mail-mailboxes/#op-get-api-v1-client-platform-mail-tenant-id-mailboxes)
- `POST /api/v1/client/platform-mail/{tenant_id}/mailboxes`: Create mailbox (https://docs.coritan.com/api/reference/client/mail/platform-mail-mailboxes/#op-post-api-v1-client-platform-mail-tenant-id-mailboxes)
- `DELETE /api/v1/client/platform-mail/{tenant_id}/mailboxes/{account_id}`: Delete mailbox (https://docs.coritan.com/api/reference/client/mail/platform-mail-mailboxes/#op-delete-api-v1-client-platform-mail-tenant-id-mailboxes-account-id)
- `GET /api/v1/client/platform-mail/{tenant_id}/mailboxes/{account_id}/app-passwords`: Mailbox app passwords (https://docs.coritan.com/api/reference/client/mail/platform-mail-mailboxes/#op-get-api-v1-client-platform-mail-tenant-id-mailboxes-account-id-app-passwords)
- `POST /api/v1/client/platform-mail/{tenant_id}/mailboxes/{account_id}/app-passwords`: Mailbox app password create (https://docs.coritan.com/api/reference/client/mail/platform-mail-mailboxes/#op-post-api-v1-client-platform-mail-tenant-id-mailboxes-account-id-app-passwords)
- `DELETE /api/v1/client/platform-mail/{tenant_id}/mailboxes/{account_id}/app-passwords/{credential_id}`: Mailbox app password delete (https://docs.coritan.com/api/reference/client/mail/platform-mail-mailboxes/#op-delete-api-v1-client-platform-mail-tenant-id-mailboxes-account-id-app-passwords)
- `PATCH /api/v1/client/platform-mail/{tenant_id}/mailboxes/{account_id}/enabled`: Mailbox enabled (https://docs.coritan.com/api/reference/client/mail/platform-mail-mailboxes/#op-patch-api-v1-client-platform-mail-tenant-id-mailboxes-account-id-enabled)
- `GET /api/v1/client/platform-mail/{tenant_id}/mailboxes/{account_id}/imports`: Mailbox imports (https://docs.coritan.com/api/reference/client/mail/platform-mail-mailboxes/#op-get-api-v1-client-platform-mail-tenant-id-mailboxes-account-id-imports)
- `POST /api/v1/client/platform-mail/{tenant_id}/mailboxes/{account_id}/imports`: Mailbox import start (https://docs.coritan.com/api/reference/client/mail/platform-mail-mailboxes/#op-post-api-v1-client-platform-mail-tenant-id-mailboxes-account-id-imports)
- `POST /api/v1/client/platform-mail/{tenant_id}/mailboxes/{account_id}/imports/oauth`: Mailbox import sign in (https://docs.coritan.com/api/reference/client/mail/platform-mail-mailboxes/#op-post-api-v1-client-platform-mail-tenant-id-mailboxes-account-id-imports-oauth)
- `POST /api/v1/client/platform-mail/{tenant_id}/mailboxes/{account_id}/imports/upload`: Mailbox import upload (https://docs.coritan.com/api/reference/client/mail/platform-mail-mailboxes/#op-post-api-v1-client-platform-mail-tenant-id-mailboxes-account-id-imports-upload)
- `POST /api/v1/client/platform-mail/{tenant_id}/mailboxes/{account_id}/imports/{import_id}/{action}`: Mailbox import steer (https://docs.coritan.com/api/reference/client/mail/platform-mail-mailboxes/#op-post-api-v1-client-platform-mail-tenant-id-mailboxes-account-id-imports-import-i)
- `POST /api/v1/client/platform-mail/{tenant_id}/mailboxes/{account_id}/password`: Mailbox password (https://docs.coritan.com/api/reference/client/mail/platform-mail-mailboxes/#op-post-api-v1-client-platform-mail-tenant-id-mailboxes-account-id-password)
- `PATCH /api/v1/client/platform-mail/{tenant_id}/mailboxes/{account_id}/quota`: Mailbox quota (https://docs.coritan.com/api/reference/client/mail/platform-mail-mailboxes/#op-patch-api-v1-client-platform-mail-tenant-id-mailboxes-account-id-quota)
- `GET /api/v1/client/platform-mail/{tenant_id}/mailboxes/{account_id}/sessions`: Mailbox sessions (https://docs.coritan.com/api/reference/client/mail/platform-mail-mailboxes/#op-get-api-v1-client-platform-mail-tenant-id-mailboxes-account-id-sessions)
- `DELETE /api/v1/client/platform-mail/{tenant_id}/mailboxes/{account_id}/sessions`: Mailbox sessions end (https://docs.coritan.com/api/reference/client/mail/platform-mail-mailboxes/#op-delete-api-v1-client-platform-mail-tenant-id-mailboxes-account-id-sessions)
- `DELETE /api/v1/client/platform-mail/{tenant_id}/mailboxes/{account_id}/sessions/{session_id}`: Mailbox session end (https://docs.coritan.com/api/reference/client/mail/platform-mail-mailboxes/#op-delete-api-v1-client-platform-mail-tenant-id-mailboxes-account-id-sessions-sessi)
- `POST /api/v1/client/platform-mail/{tenant_id}/mailboxes/{account_id}/totp`: Mailbox totp enable (https://docs.coritan.com/api/reference/client/mail/platform-mail-mailboxes/#op-post-api-v1-client-platform-mail-tenant-id-mailboxes-account-id-totp)
- `DELETE /api/v1/client/platform-mail/{tenant_id}/mailboxes/{account_id}/totp`: Mailbox totp disable (https://docs.coritan.com/api/reference/client/mail/platform-mail-mailboxes/#op-delete-api-v1-client-platform-mail-tenant-id-mailboxes-account-id-totp)
- `GET /api/v1/client/platform-mail/{tenant_id}/aliases`: List aliases (https://docs.coritan.com/api/reference/client/mail/platform-mail-aliases/#op-get-api-v1-client-platform-mail-tenant-id-aliases)
- `POST /api/v1/client/platform-mail/{tenant_id}/aliases`: Create alias (https://docs.coritan.com/api/reference/client/mail/platform-mail-aliases/#op-post-api-v1-client-platform-mail-tenant-id-aliases)
- `DELETE /api/v1/client/platform-mail/{tenant_id}/aliases/{account_id}`: Delete alias (https://docs.coritan.com/api/reference/client/mail/platform-mail-aliases/#op-delete-api-v1-client-platform-mail-tenant-id-aliases-account-id)
- `GET /api/v1/client/platform-mail/{tenant_id}/credentials`: List credentials (https://docs.coritan.com/api/reference/client/mail/platform-mail-credentials/#op-get-api-v1-client-platform-mail-tenant-id-credentials)
- `POST /api/v1/client/platform-mail/{tenant_id}/credentials`: Create credential (https://docs.coritan.com/api/reference/client/mail/platform-mail-credentials/#op-post-api-v1-client-platform-mail-tenant-id-credentials)
- `DELETE /api/v1/client/platform-mail/{tenant_id}/credentials/{account_id}`: Delete credential (https://docs.coritan.com/api/reference/client/mail/platform-mail-credentials/#op-delete-api-v1-client-platform-mail-tenant-id-credentials-account-id)
- `PATCH /api/v1/client/platform-mail/{tenant_id}/credentials/{account_id}/enabled`: Credential enabled (https://docs.coritan.com/api/reference/client/mail/platform-mail-credentials/#op-patch-api-v1-client-platform-mail-tenant-id-credentials-account-id-enabled)
- `POST /api/v1/client/platform-mail/{tenant_id}/credentials/{account_id}/rotate`: Rotate credential (https://docs.coritan.com/api/reference/client/mail/platform-mail-credentials/#op-post-api-v1-client-platform-mail-tenant-id-credentials-account-id-rotate)
- `GET /api/v1/client/platform-mail/{tenant_id}/api-keys`: List API keys (https://docs.coritan.com/api/reference/client/mail/platform-mail-api-keys/#op-get-api-v1-client-platform-mail-tenant-id-api-keys)
- `POST /api/v1/client/platform-mail/{tenant_id}/api-keys`: Create API key (https://docs.coritan.com/api/reference/client/mail/platform-mail-api-keys/#op-post-api-v1-client-platform-mail-tenant-id-api-keys)
- `DELETE /api/v1/client/platform-mail/{tenant_id}/api-keys/{key_id}`: Revoke API key (https://docs.coritan.com/api/reference/client/mail/platform-mail-api-keys/#op-delete-api-v1-client-platform-mail-tenant-id-api-keys-key-id)
- `GET /api/v1/client/platform-mail/{tenant_id}/suppressions`: List suppressions (https://docs.coritan.com/api/reference/client/mail/platform-mail-suppressions/#op-get-api-v1-client-platform-mail-tenant-id-suppressions)
- `POST /api/v1/client/platform-mail/{tenant_id}/suppressions`: Add suppression (https://docs.coritan.com/api/reference/client/mail/platform-mail-suppressions/#op-post-api-v1-client-platform-mail-tenant-id-suppressions)
- `DELETE /api/v1/client/platform-mail/{tenant_id}/suppressions/{suppression_id}`: Remove suppression (https://docs.coritan.com/api/reference/client/mail/platform-mail-suppressions/#op-delete-api-v1-client-platform-mail-tenant-id-suppressions-suppression-id)
- `GET /api/v1/client/platform-mail/{tenant_id}/webhooks`: List webhooks (https://docs.coritan.com/api/reference/client/mail/platform-mail-webhooks/#op-get-api-v1-client-platform-mail-tenant-id-webhooks)
- `POST /api/v1/client/platform-mail/{tenant_id}/webhooks`: Create webhook (https://docs.coritan.com/api/reference/client/mail/platform-mail-webhooks/#op-post-api-v1-client-platform-mail-tenant-id-webhooks)
- `DELETE /api/v1/client/platform-mail/{tenant_id}/webhooks/{webhook_id}`: Delete webhook (https://docs.coritan.com/api/reference/client/mail/platform-mail-webhooks/#op-delete-api-v1-client-platform-mail-tenant-id-webhooks-webhook-id)
- `POST /api/v1/client/platform-mail/{tenant_id}/messages`: Send message (https://docs.coritan.com/api/reference/client/mail/platform-mail/#op-post-api-v1-client-platform-mail-tenant-id-messages)
- `GET /api/v1/client/platform-mail/{tenant_id}/events`: List events (https://docs.coritan.com/api/reference/client/mail/platform-mail/#op-get-api-v1-client-platform-mail-tenant-id-events)
- `GET /api/v1/client/platform-mail/{tenant_id}/usage`: Usage report (https://docs.coritan.com/api/reference/client/mail/platform-mail/#op-get-api-v1-client-platform-mail-tenant-id-usage)
- `GET /api/v1/client/platform-mail/{tenant_id}/reputation`: Reputation report (https://docs.coritan.com/api/reference/client/mail/platform-mail/#op-get-api-v1-client-platform-mail-tenant-id-reputation)
- `POST /api/v1/client/platform-mail/{tenant_id}/limits/increase-request`: Request limit increase (https://docs.coritan.com/api/reference/client/mail/platform-mail/#op-post-api-v1-client-platform-mail-tenant-id-limits-increase-request)