/api/v1/email/send
Requires email.send. Queue a live message or capture a sandbox message without contacting recipients.
API reference
Send transactional email.
Use a sandbox key while developing and a live key after production approval and domain verification. All API requests use JSON over HTTPS and Bearer authentication.
/api/v1/email/{id}
Requires email.read. Retrieve the tenant-scoped message, recipient states, and event history.
Environment keys
mp_test_ suppresses delivery. mp_live_ requires production approval and a verified sender domain.
Before sending
Create a key
Generate a sandbox or live key with email.send. Copy it immediately because the plain key is shown only once.
Prepare live sending
Live sending requires platform approval and a verified domain matching the domain portion of from.
Send and inspect
Store the returned message UUID. Use an email.read key to retrieve recipients and delivery events.
JSON request
curl -X POST "https://nextmailer.kumulant.com/api/v1/email/send" \
-H "Authorization: Bearer mp_test_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-1048-confirmation" \
-d '{
"from": "notifications@your-domain.com",
"from_name": "Your Application",
"reply_to": "support@your-domain.com",
"to": ["customer@example.net"],
"subject": "Your order is confirmed",
"html": "<h1>Thank you</h1><p>Your order is ready.</p>",
"text": "Thank you. Your order is ready."
}'Accepted response
{"id":"uuid","status":"queued","sandbox":false}. Accepted means queued; it does not mean delivered.
Sandbox response
Sandbox requests return status: sandboxed and sandbox: true. They appear in the dashboard but are never delivered.
Idempotent replay
Reusing the same Idempotency-Key for the organization returns the existing message instead of creating another.
Retrieve message status
curl "https://nextmailer.kumulant.com/api/v1/email/MESSAGE_UUID" \
-H "Authorization: Bearer mp_live_YOUR_API_KEY"Payload and limits
Recipients
to is required and accepts an email or array. cc and bcc are optional arrays. Organization quotas determine the maximum recipients.
Content
Provide subject and at least one of html or text, or provide an active template slug with optional variables.
Optional fields
Supports from_name, reply_to, up to 30 custom headers, and up to 10 attachments of 10 MB each using multipart form data.
Common status codes
Missing key
The Bearer token is absent or does not use a supported key prefix.
Access denied
The key is invalid, expired, revoked, missing permission, blocked by its IP allowlist, or the organization cannot send.
Not found
The message or active template does not exist within the API key's organization.
Validation failed
Review the JSON error details for invalid fields, an unverified sender domain, suppression, recipient limits, or quota failures.
Rate limited
The API key exceeded the configured per-minute request limit. Retry with backoff.