# Mailionaire API

Order, track, and manage Microsoft 365 cold-email mailboxes programmatically.

Base URL: https://api.mailionaire.ch/v1
Auth header: Authorization: Bearer mk_live_...
Test mode: the same base URL with an mk_test_ key. Nothing is provisioned and
nothing is charged; orders still run queued -> prepared -> running -> completed
on a compressed clock and webhooks still fire. Mint one with
POST /keys {"environment": "sandbox"}; read GET /me to see which you are on.
Docs: https://api.mailionaire.ch/v1/docs
OpenAPI: https://api.mailionaire.ch/v1/openapi.json
Capabilities (JSON): https://api.mailionaire.ch/v1/capabilities

## Endpoints
- GET /billing — Get your subscription summary
- GET /billing/invoices — List billing invoices
- POST /billing/order-confirmations — Confirm billing for an order
- POST /billing/order-confirmations/confirm — Confirm completed Stripe Checkout
- GET /billing/usage — Get current billing-period usage
- GET /capacity — Check provisioning capacity
- GET /connections — Registrar and sequencer connection status
- DELETE /connections/registrar — Disconnect your registrar
- PUT /connections/registrar — Connect or replace your registrar credential
- POST /connections/registrar/sync — Re-read the domains at your registrar
- DELETE /connections/sequencer — Disconnect your sequencer
- PUT /connections/sequencer — Connect or replace your sequencer token
- POST /connections/sequencer/sync — Re-read your sequencer workspaces
- GET /domains — List your domains
- POST /domains — Provision mailboxes for one approved domain (alias of POST /orders).
- GET /domains/available — List domains available to order
- GET /domains/dns-drift — DNS drift across your domains
- DELETE /domains/{domain} — Cancel a domain's subscription at `effective_at` — NOT immediately. The domain keeps sending until then. Minimum term is one full billing month, so `effective_at` can be a renewal later than the next one (`minimum_term_applied: true`). Repeat calls are safe.
- GET /domains/{domain} — Get one domain
- GET /domains/{domain}/dns — Live MX/SPF/DMARC/DKIM status. Read `basis`: `target_state` (ours, compared against the records we applied) or `observed` (not ours, published facts only).
- GET /domains/{domain}/dns-drift — DNS drift for one domain
- GET /domains/{domain}/dns-drift/history — DNS drift history for one domain
- POST /domains/{domain}/dns/delegate — Delegate a domain's DNS to Cloudflare
- GET /domains/{domain}/dns/delegation — Get a domain's Cloudflare NS-delegation state
- POST /domains/{domain}/dns/recheck — Re-check a domain's mail/auth DNS
- DELETE /domains/{domain}/graph-integration — Request app-access revocation. Sandbox revocation is immediate and simulated.
- GET /domains/{domain}/graph-integration — Read tenant identity, directory-observed UPNs and app-integration state.
- PUT /domains/{domain}/graph-integration — Bind your app profile to an owned domain. Identical retries reuse the binding.
- PUT /domains/{domain}/graph-integration/provisioning-destination — Select an app profile as the provisioning destination of an unused domain.
- POST /domains/{domain}/graph-integration/refresh — Refresh simulated inventory after a sandbox order completes.
- GET /domains/{domain}/mailboxes — List mailboxes on a domain
- POST /domains/{domain}/mailboxes/export — Export a domain's mailboxes as CSV
- POST /domains/{domain}/senders/reconnect — Report a domain's live sender-reconnect posture (reconnect is automatic).
- GET /domains/{domain}/website — Read website forwarding
- PUT /domains/{domain}/website — Configure website forwarding
- POST /domains/{domain}/website/check — Check forwarding DNS connection
- PUT /domains/{domain}/workspace — Assign a domain to a sequencer workspace
- GET /events — Recent lifecycle events, newest first (poll with `?since=`).
- GET /graph/profiles — List only your app profiles. This opt-in capability is disabled by default.
- POST /graph/profiles — Register your own multitenant Entra app, without supplying a secret.
- DELETE /graph/profiles/{profile_id} — Retire an unused app profile. Revoke its domain bindings first.
- GET /graph/profiles/{profile_id} — Read an owned app profile. A foreign profile returns the same 404 as a missing one.
- GET /keys — List API keys
- POST /keys — Mint an API key
- DELETE /keys/{key_id} — Revoke an API key
- GET /mailboxes/{email} — Get a single mailbox
- PATCH /mailboxes/{email} — Rename a mailbox
- GET /mailboxes/{email}/status — One mailbox's connection and warmup status (warmup score, send/reply/bounce counts).
- GET /me — Your account, plan, limits, and which environment (live|sandbox) this key addresses.
- GET /notifications — List your notifications
- GET /orders — List your orders (newest first).
- POST /orders — Order mailboxes for one domain (name_mode: automatic|names|csv).
- POST /orders/bulk — Order mailboxes for up to 25 domains in one call.
- GET /orders/{order_id} — Poll an order until status is completed.
- GET /orders/{order_id}/logs — Get an order's provisioning log
- GET /summary — Get the whole account in one call
- GET /team/audit — Recent team and sign-in activity
- GET /team/members — List workspace members
- POST /team/members — Invite a member
- DELETE /team/members/{member_id} — Remove a member
- PATCH /team/members/{member_id} — Change a member's role
- GET /webhooks — List your webhook endpoints
- POST /webhooks — Register a webhook endpoint
- GET /webhooks/deliveries — List webhook deliveries
- GET /webhooks/deliveries/{delivery_id} — Get one webhook delivery
- POST /webhooks/deliveries/{delivery_id}/replay — Replay a webhook delivery
- DELETE /webhooks/{webhook_id} — Delete a webhook endpoint
- GET /webhooks/{webhook_id} — Get a webhook endpoint
- POST /webhooks/{webhook_id}/test — Send a test ping
- GET /workspaces — List sequencer workspaces

## Events
Register a webhook with POST /webhooks to receive these, or poll GET /events:
order.created, order.completed, order.failed, domain.ready, domain.canceled, domain.dns_drift, email.sent, email.send_failed, email.bounced, reply.received, lead.unsubscribed.

## Rate limits
300 requests/minute per key; 30/minute on writes; 10/minute on order creation.

## Idempotency
Send an `Idempotency-Key` header on any POST to make retries safe: the first
response is cached and replayed (with header `Idempotency-Replayed: true`) for
any repeat carrying the same key, without re-running the handler. `POST /orders`
additionally accepts an `idempotency_key` body field for durable, cross-process
order de-duplication.