# Run Mail Hosting for your customers

> See the mail your customers host through your organization, and manage their domains, mailboxes and sending.

Source: https://www.coritan.com/docs/organizations/mail/

In the dashboard:

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

Every Mail Hosting or SMTP Relay service a customer orders from your organization runs as a *mail tenant*: its own domains, mailboxes, credentials and sending reputation. The **Email** tab lists your tenants and shows which ones need attention. To work inside a tenant, your staff use the API on this page, which offers the same operations the customer has on their own service.

## Before you begin

- Any member of the organization can open the **Email** tab and call the two list routes.
- Opening or changing a single tenant takes the `owner`, `admin` or `support_tier3` role. Other roles get `403 Staff access required`. [Roles and permissions](/docs/organizations/roles-and-permissions/) lists who holds which role.

## Read the Email tab

1. Go to [Organizations](https://www.coritan.com/dashboard/organizations), open your organization and choose **Email**.
2. Read the four cards at the top:
   - **Tenants** counts every tenant that has not been terminated.
   - **Sending frozen** counts the tenants whose outgoing mail we have paused.
   - **Domains pending** counts the domains still waiting for their MX, SPF or DKIM records to verify.
   - **Frozen share** is the frozen tenants as a percentage of all tenants.
3. Read the **Mail tenants** table. Each row is one tenant:
   - **Tenant** shows its name, its kind and its domains.
   - **Customer** shows the customer who owns it.
   - **Status** shows where the service stands, with a **Sending frozen** or **Under review** badge when its reputation needs attention.
   - **Reputation** shows its sending tier with its bounce and complaint rates.
   - **Usage** shows its mailboxes against the plan's limit, its aliases and its storage.
   - **Since** shows the date the tenant was created.
4. To find a tenant, type part of a domain or a tenant ID in the search box, or narrow the list by kind. Choose **Refresh** to load the latest figures.

A tenant that we have flagged or frozen shows the reason under its row.

## How sending reputation works

We check each tenant's bounce and complaint rates over a recent window of its sending:

- A tenant whose rates cross the review threshold is flagged, and the table shows **Under review**. It keeps sending.
- A tenant whose rates cross the freeze threshold stops sending, and the table shows **Sending frozen**. The note under the row gives the rates that caused it.
- Only Coritan can lift a freeze. Clean up the list the tenant sends to, add the addresses that bounced to its suppression list, then [contact support](https://www.coritan.com/dashboard/support).

The tier decides which pool of sending addresses carries the tenant's mail. New tenants start on `probation`; the other tiers are `established` and `dedicated`. A review once a day promotes a tenant from `probation` after 14 clean days or 5,000 clean messages. A tenant under review cannot leave `probation`, and an `established` one goes back to it at the next daily review. Your customers do not see tiers or pools. [Sending reputation and deliverability](/docs/mail/smtp-relay/deliverability/) explains what they see, and when their sending pauses.

## Result

You know which tenants are frozen, under review or waiting on DNS records, and which customer owns each one.

## Troubleshooting

`403 Staff access required`
: Your role can read the tenant list but cannot open a tenant. Ask an owner or an admin to do the work, or to change your role.

`404 Mail service not found in this organization`
: The tenant ID does not belong to this organization. Take the `id` from the tenant list.

A domain stays in **Domains pending**
: Read the records the domain needs with `GET .../domains/{domain_id}/records`, publish them at the domain's DNS host, then call `POST .../domains/{domain_id}/verify`. [Mail DNS records](/docs/mail/dns-records/) explains each record.

## Related

- [How Mail Hosting works](/docs/mail/mail-hosting/)
- [How SMTP Relay works](/docs/mail/smtp-relay/)
- [Mail DNS records](/docs/mail/dns-records/)
- [Customer services](/docs/organizations/customer-services/)
- [Let customers use Mail Hosting and SMTP Relay](/docs/organizations/storefront/portal-mail/)

## With the API

Every call takes a member's access token as `Authorization: Bearer $CORITAN_TOKEN`.

### List tenants

```bash
curl "https://api.coritan.com/api/v1/orgs/acme/mail/tenants?kind=relay&q=example.com" \
  -H "Authorization: Bearer $CORITAN_TOKEN"
```

| Parameter | Meaning |
| --- | --- |
| `kind` | `hosting` for Mail Hosting or `relay` for SMTP Relay. |
| `customer_id` | Only the tenants of this customer. |
| `q` | Part of a domain name or a tenant ID, up to 120 characters. |
| `limit` | How many of the newest tenants to read, 1–500. The default is 100, and `q` searches within them. |

The answer is `{"items": [...], "total": n}`. Each item carries the tenant's `id`, `kind`, `status`, `tier`, `bounce_rate_pct`, `complaint_rate_pct`, `sending_frozen`, `review_flag`, `reputation_note` and plan limits, plus `domains`, the owning `customer` (`id`, `email`, `name`), the linked `org_service` (`id`, `status`, `hostname`) and `counts` of mailboxes, aliases, groups, relay credentials and domains.

`GET /api/v1/orgs/acme/mail/overview` answers the three counts behind the cards: `tenants`, `sending_frozen` and `domains_pending`.

### Work inside a tenant

Every route below starts with `/api/v1/orgs/acme/mail/tenants/{tenant_id}` and needs the `owner`, `admin` or `support_tier3` role. `GET` on that path alone answers the tenant's summary.

| Area | Routes and request fields |
| --- | --- |
| Domains | `GET` and `POST /domains` (`domain`, `primary`); `GET /domains/{domain_id}/records`; `POST /domains/{domain_id}/verify`; `PATCH /domains/{domain_id}/dmarc` (`stage` is `none`, `quarantine` or `reject`; `pinned`); `DELETE /domains/{domain_id}` |
| Mailboxes | `GET` and `POST /mailboxes` (`domain_id`, `local_part`, and optionally `password` of 12–128 characters, `display_name`, `quota_bytes` of at least 100 MiB); `POST /mailboxes/{account_id}/password`; `PATCH /mailboxes/{account_id}/quota` (`quota_bytes`); `PATCH /mailboxes/{account_id}/enabled` (`enabled`); `DELETE /mailboxes/{account_id}` |
| Mailbox security | `GET`, `POST` (`label`) and `DELETE /mailboxes/{account_id}/app-passwords/{credential_id}`; `POST` and `DELETE /mailboxes/{account_id}/totp`; `GET /mailboxes/{account_id}/sessions`, `DELETE` one session or all of them |
| Imports | `GET` and `POST /mailboxes/{account_id}/imports` (`host`, `username`, `password`, `folders`, `since`, `until`); `POST .../imports/oauth` (`provider` is `google` or `microsoft`); `POST .../imports/upload` as a multipart form with `file`; `POST .../imports/{import_id}/pause`, `resume` or `cancel` |
| Aliases | `GET` and `POST /aliases` (`domain_id`, `local_part`, `targets` of 1–50 addresses); `DELETE /aliases/{account_id}` |
| SMTP credentials | `GET` and `POST /credentials` (`domain_id`, `label`); `POST /credentials/{account_id}/rotate`; `PATCH /credentials/{account_id}/enabled`; `DELETE /credentials/{account_id}` |
| API keys | `GET` and `POST /api-keys` (`label`); `DELETE /api-keys/{key_id}` |
| Sending | `PATCH /category` (`default_category` is `transactional` or `marketing`); `POST /messages` (`from`, `to`, `subject`, `text` or `html`); `GET`, `POST` (`address`) and `DELETE /suppressions/{suppression_id}`; `GET`, `POST` (`url`, `events`) and `DELETE /webhooks/{webhook_id}` |
| Reports | `GET /events` (`category`, `recipient`, `hours` of 1–2160, `limit` of 1–500); `GET /usage` (`days` of 1–365); `GET /reputation` (`limit` of 1–200) |

`POST /limits/increase-request` exists on this path too, but it answers `400` for staff. A customer asks for a higher hourly limit from their own portal, and only Coritan can raise it; see [Pass on a request for a higher limit](/docs/organizations/storefront/portal-mail/#pass-on-a-request-for-a-higher-limit).

A password reset with no `password` in the body sets a random password and returns it in the answer. For a mailbox it also turns off two-factor authentication and signs out every webmail session. For example, to add a mailbox:

```bash
curl -X POST "https://api.coritan.com/api/v1/orgs/acme/mail/tenants/42/mailboxes" \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"domain_id": 7, "local_part": "alex", "display_name": "Alex"}'
```

Each area behaves as it does for the customer, so the mail pages explain the details: [mailboxes](/docs/mail/mail-hosting/mailboxes/), [aliases](/docs/mail/mail-hosting/aliases/), [moving mail in](/docs/mail/mail-hosting/move-mail-in/), [SMTP credentials](/docs/mail/smtp-relay/credentials/), [suppressions](/docs/mail/smtp-relay/suppressions/) and [webhooks](/docs/mail/smtp-relay/webhooks/). The full request and response shapes are in the [API reference](/docs/api/reference/organizations/).

## API

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