Skip to content
MoMail Docs

Domains

Manage custom domains for receiving emails. Before you can receive emails on a domain, it must be verified via DNS TXT record and configured with MoMail’s MX records.

Adding a domain

Section titled “Adding a domain”

Domain limits by plan:

  • Free: up to FREE_MAX_CUSTOM_DOMAINS (env var, default 0)
  • Pro: up to 10 domains (tier-config)

After adding a domain in the Dashboard, copy the verification token and DNS instructions from the expanded domain card.

List domains

Section titled “List domains”
GET /api/domains

Requires Dashboard session (cookies).

Response

Section titled “Response”
{
  "success": true,
  "data": [
    {
      "domain_id": "dom_abc123",
      "domain_name": "example.com",
      "verification_token": "momail-verify=xyz789abc...",
      "verified": true,
      "mx_configured": true,
      "created_at": "2024-01-15T10:30:00.000Z",
      "mailbox_count": 2
    }
  ],
  "meta": {
    "plan": "pro",
    "domain_limit": 10,
    "domain_count": 1,
    "can_add_domain": true
  }
}
FieldDescription
mailbox_countActive mailboxes still using this domain

Create domain

Section titled “Create domain”
POST /api/domains

Body: { "domain": "example.com" }

Verify domain

Section titled “Verify domain”
POST /api/domains/{id}/verify

Checks TXT ownership and MX pointing to mx.momail.io.

Migrate mailboxes (change domain)

Section titled “Migrate mailboxes (change domain)”

Move all active mailboxes from one domain to another (e.g. custom domain → user.momail.io) without losing stored emails. Historical messages stay linked by mailbox_id; only mailboxes.email_address and routing are updated.

POST /api/domains/{id}/migrate-mailboxes

Body:

{
  "target_domain": "user.momail.io",
  "dry_run": true
}
  • dry_run: true — preview from_email → to_email mappings only
  • dry_run: false — apply migration

If the target address is already taken, MoMail appends a 6-character hex suffix with a dot: james.bond → [email protected].

Response

Section titled “Response”
{
  "success": true,
  "data": {
    "dry_run": true,
    "migrated_count": 0,
    "renamed_count": 1,
    "migrations": [
      {
        "mailbox_id": "mb-uuid",
        "from_email": "[email protected]",
        "to_email": "[email protected]",
        "renamed": false
      }
    ]
  }
}

Delete domain

Section titled “Delete domain”
DELETE /api/domains/{id}

Returns 409 DOMAIN_HAS_MAILBOXES if any active mailbox still uses this domain. Migrate them first.

{
  "success": false,
  "error": {
    "code": "DOMAIN_HAS_MAILBOXES",
    "message": "Migrate all mailboxes off this domain before deleting it.",
    "details": { "mailbox_count": 2, "domain_name": "example.com" }
  }
}

DNS configuration

Section titled “DNS configuration”
TypeNameValue
TXT@momail-verify={your_token}
MX@priority 10 → mx.momail.io