Internal mail tenants

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.

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).

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, Add a sending domain).
• Create and manage mailboxes and aliases (Create and manage mailboxes, Forward addresses with 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).
• 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).

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).

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).

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.

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).

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.

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).

GET /api/v1/client/platform-mail/{tenant_id} returns the tenant's summary, as the summary of a Mail Hosting or SMTP Relay 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:

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"}'

{"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.