Organization Model¶

The multi-tenant hierarchy that keeps everything organized: who owns what, how quotas work, and how Mailyte maps to your upstream system. Field lists below are verified against database/models/core.py as of 2026-08-30.

The Hierarchy¶

Mailyte uses a three-level hierarchy to organize tenants:

Organization
├── Domain (acme.com)
│   ├── Email Account (alice@acme.com)
│   ├── Email Account (bob@acme.com)
│   └── Alias (support@acme.com → alice@acme.com)
└── Domain (acme.io)
    ├── Email Account (hello@acme.io)
    └── Alias (info@acme.io → hello@acme.io)

Think of it like a company structure: the Organization is the company, Domains are departments, and Email Accounts are employees. Aliases are name badges — they point to a real person but aren't a person themselves.

All three levels use ULID primary keys — 26-character, time-sortable strings like 01J5YGKB3ZJR4DPNZN9SMTHF4R — and all three carry their own external_id for mapping to an upstream system.

Organization¶

The top-level tenant. This is typically one of your customers.

The external_id Field¶

This is how you connect Mailyte to your own system. When your app creates an organization via the API, you pass your own customer ID as external_id:

POST /api/v1/organizations/
X-API-Key: <platform-scoped API key>
Content-Type: application/json

{
  "name": "Acme Corp",
  "external_id": "cust_abc123"
}

Creating organizations is a platform-level action — it requires an admin-scoped API key with platform scope, not a tenant credential.

Domain¶

A mail domain under an organization. One org can own many domains.

Before a domain can send or receive email reliably, its DNS must be set up. Creating a domain returns the exact records to add (MX, SPF, DKIM, DMARC), and the API's verification endpoint checks live DNS against them.

Email Account¶

A mailbox under a domain. This is a real account with storage and authentication.

Email accounts can send (SMTP, webmail, or API), receive, and be accessed via IMAP/POP3/JMAP. An account can also hold SMTP credentials — per-application API keys for sending that don't expose the mailbox password and can be rotated or revoked independently (with immediate effect, via a Dovecot auth-cache flush).

Alias¶

A forwarding address that doesn't have its own mailbox.

Aliases are lightweight. They don't consume storage quota because they don't store mail — they just redirect it.

Quotas and Limits¶

Quotas flow down the hierarchy, with each level able to override the one above:

graph TB
    Org["Organization<br>storage_quotas / rate_limits (JSON defaults)"]
    D1["Domain: acme.com<br>max_quota, overrides"]
    D2["Domain: acme.io<br>max_quota, overrides"]
    A1["alice@acme.com<br>storage_quota: 1 GB"]
    A2["bob@acme.com<br>storage_quota: 1 GB"]
    A3["hello@acme.io<br>storage_quota: 2 GB"]

    Org --> D1
    Org --> D2
    D1 --> A1
    D1 --> A2
    D2 --> A3

    style Org fill:#e1f5fe
    style D1 fill:#f3e5f5
    style D2 fill:#f3e5f5

• Storage: each account has a byte quota; each domain a max_quota and max_users cap; the org sets the defaults. The storage_usage worker keeps storage_used current from Dovecot's own QUOTA figures and fires warning/exceeded webhooks.
• Rate limits: the rate_limits JSON at org level (overridable per domain) feeds the rate_limiter service, which Postfix consults per message.
• Operator overrides: quotas edited by hand through the console set quota_override, which stops the upstream plan sync from silently reverting them.

Lifecycle¶

A typical lifecycle looks like:

1. Create org (platform-scoped API key)
2. Add domain (API returns required DNS records)
3. Verify domain (API checks live DNS after you've added the records)
4. Create accounts under the domain
5. Set up aliases as needed
6. Issue SMTP credentials for applications that send

To tear down, work in reverse — the API enforces it: deleting an organization returns 400 while it still has domains or accounts. Delete accounts, then domains, then the org. Or just deactivate the org to stop all mail flow without deleting data.