> ## Documentation Index > Fetch the complete documentation index at: https://docs.stackshift.cloud/llms.txt > Use this file to discover all available pages before exploring further. # Mailboxes > Host real mailboxes on your own domain: add the domain, create mailboxes, aliases and groups, route addresses, bring mail over from another provider and connect any mail app. > [!NOTE] > > **Not yet released.** This guide describes implemented changes awaiting rollout. Availability requires the corresponding backend and dashboard release. ## Goal Give people on your team an inbox at your domain, route the other addresses where they belong, and connect them to the apps they already use. ## Prerequisites * A domain you control and can edit DNS for * A StackShift API key or a signed-in dashboard session for the workspace * For each mailbox: a person with a StackShift account in the workspace, or an email address StackShift can invite ## Workflow **Step 1** Add the domain with POST /mail/mailbox-domains. The response lists the DNS records to publish. **Step 2** Publish the records yourself, or let StackShift write them through a connected Cloudflare account, then verify the domain. **Step 3** Create a mailbox for each person, with an owner, a plan and an invitation. **Step 4** Add aliases, groups and routing rules for the addresses that are not a single person. **Step 5** Bring existing mail over from Gmail, Microsoft 365 or any IMAP server, then switch. **Step 6** Connect each person to the dashboard inbox, a mail app or a phone. ## Domains A mailbox domain is a domain that StackShift receives mail for. It is separate from a sending domain: sending domains authenticate mail your app sends through the API, while mailbox domains receive mail for people. The same domain can be both. * POST /mail/mailbox-domains with \{ "domain": "example.com" } returns the domain, its verification token and the records to publish. Use a domain you own, not a public suffix. * GET /mail/mailbox-domains and GET /mail/mailbox-domains/\{domainId} return the status, the records and any MX record found at your DNS provider. * POST /mail/mailbox-domains/\{domainId}/verify checks DNS again. A domain becomes active once the MX record points at StackShift. * PATCH /mail/mailbox-domains/\{domainId} sets catchAll (a route target or null), retentionDays (null keeps mail forever) and addonStorageUnits (extra storage in 10 GB units). * DELETE /mail/mailbox-domains/\{domainId} removes an empty domain. * To publish the records for you, connect Cloudflare with PUT /mail/mailbox-dns/cloudflare (an API token and the domain), then POST /mail/mailbox-domains/\{domainId}/dns/apply. GET /mail/mailbox-domains/\{domainId}/dns/applications shows what was written. ## Mailboxes * POST /mail/mailboxes takes domainId, localPart, displayName, kind and a plan. kind is person (one owner) or shared (a team address several people open). * For a person mailbox, set ownerUserId for someone already in the workspace, or ownerEmail to invite them. An invited owner chooses their own password when they accept. * GET /mail/mailboxes lists mailboxes, optionally filtered by domainId. PATCH /mail/mailboxes/\{mailboxId} changes displayName, quotaBytes, plan and aiEnabled. * GET /mail/mailbox-plans lists the plans with their storage. Mailbox pricing is per mailbox per month. Groups, aliases and forwarding are free. * POST /mail/mailboxes/\{mailboxId}/suspend and /resume stop and restore sign-in and delivery. DELETE /mail/mailboxes/\{mailboxId} removes the mailbox and purges its mail. * POST /mail/mailboxes/\{mailboxId}/password-reset starts a password reset for the owner. POST /mail/mailboxes/\{mailboxId}/invitation/resend sends the invitation again. * Shared mailboxes have members: GET, POST and DELETE under /mail/mailboxes/\{mailboxId}/members. Each member keeps their own read state. * GET /mail/mailbox-usage returns storage used per domain and mailbox. * POST /mail/retention-holds with a mailboxId and a reason keeps a mailbox's mail from being removed by retention. Release it with DELETE /mail/retention-holds/\{holdId}. ## Pricing and payment Mailboxes are paid monthly. Groups, aliases and forwarding are free. * Basic is 10 GB for ₦2,500 a month. Pro is 50 GB for ₦6,000 a month. Extra domain storage is ₦1,500 a month for each 10 GB. GET /mail/mailbox-plans returns the current prices, with usdExchangeRate for a dollar estimate. * You pay the first month when you create a mailbox. The mailbox is awaiting\_payment until then. Open billing.pendingOrder.checkoutUrl to pay by card; the mailbox is set up as soon as the payment clears, and an invited owner gets the invitation only after that. A mailbox that is never paid is removed after 48 hours. * Every month the renewal is taken from your Naira wallet first. If that doesn’t cover it and your USD wallet does, it’s paid from your USD wallet at the StackShift rate. Otherwise your saved card is charged in Naira. If it fails, we tell you and the mailbox keeps working for 7 days. * After 7 days the mailbox is paused, not deleted. It cannot send or receive, and all mail is kept. Pay the renewal and it comes back at once. If extra storage goes unpaid, every mailbox on that domain is paused until the storage is paid. * Upgrading from Basic to Pro charges the price difference for the rest of the current month, and the renewal date stays the same. Downgrading from Pro to Basic applies at once, with no refund, and the next renewal is at the lower price. * Adding extra storage charges the first month when the domain has none, or the added storage for the rest of the month when it already has some. Removing storage applies at once, with no refund. * A mailbox or storage change that needs a payment returns a pending order. Pay it with POST /mail/mailbox-orders/\{orderId}/checkout, or cancel it with DELETE /mail/mailbox-orders/\{orderId}. Pay a failed renewal with POST /mail/mailboxes/\{mailboxId}/renewal-checkout or POST /mail/mailbox-domains/\{domainId}/storage-renewal-checkout. ## Aliases, groups and routing * An alias is another address for one mailbox: POST /mail/aliases with mailboxId, localPart and sendAs. With sendAs on, the person can send from the alias. * A group is an address that delivers to several mailboxes: POST /mail/groups with domainId, localPart, memberIds and an optional moderatorId. * A route sends an address or pattern to one to five targets: POST /mail/routes with domainId, pattern, priority and targets. Patterns use letters, numbers, dots, hyphens, underscores and \* wildcards. * Target kinds are mailbox (mailboxId), group (groupId), app (an https webhookUrl), support (a Support channel), forward (an address outside the domain) and reject. A reject target cannot be combined with others. * A route with a mailbox target and an app target delivers to the person and calls your app. For example, orders@ can go to a teammate and to your order system. * The domain catch-all is off by default. Turn it on with PATCH /mail/mailbox-domains/\{domainId} and expect more spam. * GET /mail/routes/app-health shows whether each app route is receiving. POST /mail/routes/\{routeId}/retry-deliveries replays failed deliveries to your app. * Replies domains and inbound webhooks keep working. An app route is the same webhook delivery, now selectable per address. ## Bring mail over from another provider * POST /mail/mailbox-imports starts a copy with a domainId, a source and one account per mailbox: the mailboxId, the old username and the old password. * source is google (Gmail and Google Workspace), microsoft (Microsoft 365) or imap (any server, with host and port). Use an app password where the old provider requires one. * The copy runs in the background. GET /mail/mailbox-imports/\{importId} shows progress for each mailbox. Cancel the job or skip one mailbox with POST .../cancel and POST .../mailboxes/\{mailboxId}/skip. * When the copy has caught up, POST /mail/mailbox-imports/\{importId}/switch with when set to now or tonight. After the switch, change the MX record and mail flows to StackShift. * The old passwords are used only for the copy and are stored encrypted. ## Mail apps and phones * Incoming (IMAP): imap.mail.stackshift.cloud, port 993, SSL. * Outgoing (SMTP submission): submit.mail.stackshift.cloud, port 587, STARTTLS. * The username is the full mailbox address. Sign in with an app password, not the account password: POST /mail/mailboxes/\{mailboxId}/app-passwords returns the secret once. Revoke it with DELETE. * GET /mail/mailbox-client-settings returns the hosts and ports for your workspace. * POST /mail/mailboxes/\{mailboxId}/mobileconfig returns a one-time link to an Apple configuration profile that sets up Mail on iPhone and Mac in one tap. * GET /mail/mailboxes/\{mailboxId}/devices lists the apps and browsers signed in, and DELETE /mail/mailboxes/\{mailboxId}/devices/\{kind}/\{deviceId} signs one out. * Mail sent from a mailbox is signed with your domain's DKIM key and goes out on its own people-mail stream, so it never shares reputation with your campaigns. ## Official SDKs and CLI The same endpoints are available in the TypeScript, Python and Go SDKs and as `stackshift mail` commands. See the CLI reference for mail domains, mailboxes, aliases, groups, routes and imports. ## Expected result > [!TIP] > > Every person has a working mailbox, every other address on the domain reaches a mailbox, a group or your app, and mail arrives and sends from any client. ## Common failures > [!WARNING] > > * domain\_taken: the domain already belongs to another workspace. Remove it there first or use a different domain. > * address\_taken: the address is already a mailbox, alias, group or route on this domain. > * invitation\_pending: the owner has not accepted the invitation. Resend it with POST /mail/mailboxes/\{mailboxId}/invitation/resend. > * quota\_exceeded: the domain storage pool is full. Raise addonStorageUnits on the domain or delete mail first. > * renewal\_unpaid: pay the mailbox renewal before changing its plan. > * order\_open: a payment is already open for this change. Finish or cancel it first. > * paused\_for\_payment: a mailbox paused for an unpaid renewal cannot be resumed. Pay the renewal instead. > * domain\_not\_empty: a domain with mailboxes cannot be deleted. Delete or move the mailboxes first. > * Mail does not arrive: the MX record is missing or still points at the old provider. Check the domain with POST /mail/mailbox-domains/\{domainId}/verify. ## Related guides > **[Mailbox AI, the screener and agent tools](https://docs.stackshift.cloud/stackshift-mail/mailbox-ai-and-agents.md)** > > Turn on AI for a domain, summarize and draft with it, screen unknown senders, and let an agent work in only the mailboxes you choose. > **[Inbox placement](https://docs.stackshift.cloud/stackshift-mail/inbox-placement.md)** > > What StackShift does so a new domain reaches the inbox, what it cannot promise, and how to see where your domain stands. > **[Sender domains and DNS](https://docs.stackshift.cloud/stackshift-mail/sender-domains-and-dns.md)** > > Create and verify outbound sender domains, inspect SPF, DKIM, DMARC, and return-path record status, and know what the domain status fields mean. > **[Inbound mail](https://docs.stackshift.cloud/stackshift-mail/inbound-mail.md)** > > Receive mail on verified domains, inspect parsed messages, and securely download scanned raw messages and attachments. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.