10 · MailMarco API

Mailboxes

Real mailboxes your customers log into — IMAP, SMTP, calendar and contacts — provisioned through the API.

The model#

Four resources, in the order you create them. Each one only makes sense once the one above it exists.

Hosting domains#

Adding a domain returns the MX record to publish. Nothing can be created inside it until verification sees that record in DNS.

curl -X POST https://api.mailmarco.com/v1/mailbox-domains \
  -H "authorization: Bearer $MAILMARCO_ACCESS_TOKEN" \
  -H "content-type: application/json" \
  -d '{"domain":"mail.example.com"}'

{
  "id": "9a1b2c3d-4e5f-4061-8273-8495a6b7c8d9",
  "domain": "mail.example.com",
  "status": "pending",
  "mxHost": "mail.mailmarco.com",
  "mxPriority": 10,
  "catchAllMailboxId": null,
  "verifiedAt": null,
  "dnsRecord": {
    "host": "mail.example.com",
    "recordType": "MX",
    "value": "10 mail.mailmarco.com",
    "ttl": 3600
  }
}

{ "id": "9a1b2c3d-…", "status": "verified", "verifiedAt": "2026-07-31T09:12:44.000Z" }

DNS caches. A record published seconds ago may not be visible yet, and the answer is to wait and call verify again rather than to re-create the domain.

Catch-all

A catch-all points every address in the domain that matches nothing else at one mailbox. It is off by default, because a catch-all receives every typo and every dictionary attack aimed at the domain.

Mailboxes#

curl -X POST https://api.mailmarco.com/v1/mailboxes \
  -H "authorization: Bearer $MAILMARCO_ACCESS_TOKEN" \
  -H "content-type: application/json" \
  -d '{
    "mailboxDomainId": "9a1b2c3d-4e5f-4061-8273-8495a6b7c8d9",
    "localPart": "info",
    "displayName": "Info Desk",
    "password": "correct-horse-battery-staple"
  }'

{
  "id": "1f2e3d4c-5b6a-4978-8695-a4b3c2d1e0f9",
  "address": "[email protected]",
  "displayName": "Info Desk",
  "quotaBytes": 1073741824,
  "status": "active",
  "provisioned": true,
  "password": "correct-horse-battery-staple"
}

Mailbox passwords have a higher minimum than dashboard passwords (12 characters) because they are typed into third-party mail clients and used over IMAP and SMTP, where there is no MFA, no session concept and no rate-limit UI. A compromise hands over the whole mail history and an authenticated relay.

provisioned is not decoration

A mailbox exists in two places: a record here and an account in the mail server itself. If the second write fails, provisioned is false and syncError carries the reason — the address will not accept mail yet. Reconciliation retries it; a mailbox that stays unprovisioned is a fault to surface, not a state to hide.

Delete, restore, purge

Deleting is reversible for 30 days. Purging is not, and is refused until the recovery window has elapsed — there is no force flag, so no single call can go from a live mailbox to destroyed mail.

Aliases#

An alias is another address that delivers into an existing mailbox. Only the local part is accepted: the domain is taken from the target mailbox, so an alias can only ever be minted inside a domain you have already proven you own.

{ "id": "…", "mailboxId": "1f2e3d4c-…", "address": "[email protected]" }

Forwarding#

A forwarder sends arriving mail on to an external address. The one decision that matters is whether a copy stays behind.

{
  "id": "…",
  "mailboxId": "1f2e3d4c-…",
  "destination": "[email protected]",
  "keepCopy": true,
  "enabled": true,
  "status": "active"
}

PATCH /v1/forwarders/:id toggles enabled or keepCopy; DELETE /v1/forwarders/:id removes the rule.

Connecting a client#

Mailboxes are reached with standard protocols, so any mail, calendar or contacts client works. The dashboard shows these per mailbox with copy buttons; the values are below for reference. The username is always the full address.

Calendar and contacts

Every mailbox gets a calendar and an address book when it is created. Most clients need only the server URL and will discover the rest; the direct collection URLs are there for clients that ask for a collection address.

Server URL      https://mail.mailmarco.com/
Username        [email protected]

CalDAV  (direct) https://mail.mailmarco.com/dav/cal/info%40mail.example.com/default/
CardDAV (direct) https://mail.mailmarco.com/dav/card/info%40mail.example.com/default/

The address is percent-encoded in the path — it contains an @, and un-encoded the URL's authority is ambiguous.

Endpoints#