Send API reference
Send a JSON request from your server. All recipients are resolved from the authenticated website and optional group.
POST https://mailmanaged.com/api/v1/messages
Authorization: Bearer YOUR_SITE_TOKEN
Accept: application/json
Content-Type: application/json
Idempotency-Key: contact-submission-4821
{
"subject": "New contact enquiry",
"text": "Name: Taylor\nMessage: Let’s talk about a project.",
"reply_to": "taylor@example.com",
"group": "contact"
}| Field | Requirement |
|---|---|
| subject | Required; up to 998 characters; no line breaks |
| text / html | At least one body; up to 262,144 characters each; 600 KB request maximum |
| reply_to | Optional valid email address |
| group | Optional registered group slug |
Accepted response
HTTP/1.1 202 Accepted
{
"id": "01KMAILMANAGEDMESSAGEID0000",
"status": "queued",
"deliveries": 2,
"replayed": false
}Acceptance means the message is durably queued. Delivery to the recipient’s mail server is confirmed separately by Mailgun events.
Idempotency
Send a unique 8–128 character key for each logical submission. Repeating the same key and payload returns HTTP 200 and the original message ID without using more allowance. Reusing a key with different content returns 409. Keys expire after 24 hours.
Errors and throttling
| Status | Meaning |
|---|---|
| 401 / 403 | Invalid token, insufficient permission, unverified website, or a security hold shown in your dashboard |
| 402 | Subscription required or website paused |
| 409 | Idempotency key reused with a different payload |
| 413 / 422 | Oversized or invalid message, unknown group, or no eligible recipients |
| 429 | Rate or usage limit; honor the Retry-After header |
Use bounded exponential backoff for transient errors. Keep the same idempotency key across retries. Minute, hour, day, and calendar-month windows use UTC.
Read delivery status
GET /api/v1/messages/{message_id}
Authorization: Bearer YOUR_SITE_TOKENThis returns the message’s per-recipient delivery results. A token can only read messages belonging to its own website.