Developers
API reference
Authenticate with API keys, send mail with POST /send/, handle errors and use idempotency keys safely.
Authentication
Base URL: /api/v1. Create a key in Settings → API keys (shown once, optional expiry) and send it in a header:
Authorization: Api-Key mf_...Never put keys in query strings or logs. API keys act with Admin rights. Invalid, revoked or expired keys return 401. Requests are rate limited per account (600 per hour by default).
Send mail
Send a unique Idempotency-Key (up to 128 characters) per message to POST /send/. Replaying the same key returns the original result with idempotent_replay: true and does not send again. A 409 means that key is still pending or its outcome is unknown: don't retry with a new key.
Responses and errors
| Status | Meaning |
|---|---|
202 | Accepted for delivery. |
409 idempotency_conflict | Same key still pending or outcome unknown. |
403 sender_not_allowed | A Member tried to send as another mailbox. |
403 sending_suspended | The account or sender mailbox is paused. |
403 plan_limit | Creating a domain or user beyond your plan. |
429 warmup_limit | Account-wide warm-up cap reached; body includes limit and used. |
429 quota_exceeded | Rolling 24-hour recipient limit reached. |
502 provider_rejected | Definitively refused; quota released. Fix the cause, then retry. |
502 provider_outcome_unknown | Timed out; the message may have been sent. Do not resend blindly. |
Other endpoints
| Endpoint | Purpose |
|---|---|
GET /me/ | Account, role, plan limits/usage and sending status. |
GET /client-settings/ | IMAP/SMTP host and ports, webmail URL. |
GET, POST /domains/ | List or add domains. |
POST /domains/{id}/verify/ | Check the ownership TXT record. |
GET /domains/{id}/dns-records/ | Every record with live status. |
GET, POST /mailboxes/ | List or create mailboxes. |
POST /mailboxes/{id}/reset-password/ | Issue one new password for the mailbox and its linked vizsu sign-in (shown once; the response reports each target). |
GET /usage/ | Recipients used and remaining per mailbox. |
GET, POST /api-keys/ | List or create keys; DELETE /api-keys/{id}/ revokes. |
Not yet available: message search, outbound event webhooks and quota history.