Your own sites and programs talk to mailrust over a small JSON API: send an email from a mailbox, add a subscriber to a list, send a lead into an outreach campaign and learn what became of it. For AI agents there is a separate door, MCP.
Requests
| Method and address | What it does |
|---|---|
POST /api/v1/send | Send an email |
GET /api/v1/lists | Your newsletter lists |
POST /api/v1/subscribers | Add a subscriber |
DELETE /api/v1/subscribers | Unsubscribe |
GET /api/v1/campaigns | Your outreach campaigns |
POST /api/v1/prospects | Add prospects to a campaign |
GET /api/v1/prospects | What became of a prospect |
POST /api/v1/prospects/state | Report the outcome |
Keys
Create a key under Settings → Site keys:
| Field | What it means |
|---|---|
| What the key is for | A name you recognise, for example the site's domain |
| Mailbox | The mailbox the key sends from; you must be allowed to send from it |
| Emails per day | The key sends no more than this, in case the site gets hacked |
| May add prospects to campaigns | Only for a site with a lead form or a CRM; a key that sends "order received" does not need it |
The key starts with mr_ and is shown once. mailrust keeps only its fingerprint. Send it in every request:
curl https://mail.example.com/api/v1/lists \
-H "Authorization: Bearer mr_..."
Revoke stops a key at once.
Answers
Every answer is JSON with an ok field. On a refusal, error explains it in plain words:
{ "ok": false, "error": "`subject` is required, 300 characters at most" }
| Status | Meaning |
|---|---|
200, 202 | Done; 202 means the email is queued |
400 | The request is incomplete or malformed |
401 | The key is missing, unknown or revoked |
403 | The key may not do this, for example campaigns without the prospects permission |
404 | No such list, campaign or prospect |
409 | The request does not apply right now; error says why |
413 | The email is over one megabyte |
422 | Nobody to write to, or a reused Idempotency-Key with a different request |
429 | A limit is reached |
Sending twice by mistake
Add an Idempotency-Key header to POST /api/v1/send. A repeat with the same key and the same body within 24 hours gets the first answer again, with the header Idempotent-Replayed: true, and nothing is sent twice. The key is 1 to 200 printable ASCII characters, for example the order number.
Limits
| What | Limit |
|---|---|
| Recipients in one email request | 50, each gets a copy of their own |
| Subject | 300 characters |
| Email body | 1 MB |
| Emails per key per day | Set on the key |
| New subscribers per list per hour | 600 |
| Prospects in one request | 100 |