Sends
The send endpoint is the core of Numonic. Every email is pre-flight checked against your domain configuration and suppression list before being handed off to SES.Send an email
POST /api/v1/send
202 Accepted immediately.
Authentication
AcceptsX-API-Key or Authorization: Bearer (JWT).
Request
curl -X POST https://api.numonic.com/api/v1/send \
-H "X-API-Key: nmc_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"from": "noreply@yourapp.com",
"to": ["user@example.com"],
"subject": "Your order is confirmed",
"html": "<p>Thanks for your order.</p>",
"text": "Thanks for your order."
}'
curl -X POST https://api.numonic.com/api/v1/send \
-H "X-API-Key: nmc_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"from": "noreply@yourapp.com",
"to": ["user@example.com"],
"cc": ["manager@example.com"],
"bcc": ["audit@yourapp.com"],
"reply_to": "support@yourapp.com",
"subject": "Order #12345 Confirmation",
"html": "<h1>Order Confirmed</h1><p>Your order #12345 has been confirmed.</p>",
"text": "Order Confirmed. Your order #12345 has been confirmed.",
"idempotency_key": "order-12345-confirmation"
}'
Body parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
from | string | Yes | Sender email. Must use a verified domain in your account |
to | string[] | Yes | Recipient addresses. Array, minimum 1 |
subject | string | Yes | Email subject |
html | string | Yes* | HTML body. At least one of html or text required |
text | string | Yes* | Plain text body |
cc | string[] | No | CC recipients |
bcc | string[] | No | BCC recipients |
reply_to | string | No | Reply-to address |
idempotency_key | string | No | Deduplication key. Auto-generated if omitted |
Response 202
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"status": "queued",
"idempotency_key": "order-12345-confirmation",
"queued_at": "2026-04-09T10:30:00.000Z",
"idempotent": false
}
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"status": "queued",
"idempotency_key": "order-12345-confirmation",
"queued_at": "2026-04-09T10:30:00.000Z",
"idempotent": false,
"suppressed_recipients": ["bounced@example.com"]
}
Response fields
| Field | Description |
|---|---|
id | UUID for this send. Use to query status |
status | Current status — see statuses |
idempotency_key | Key used for this send |
queued_at | ISO 8601 timestamp when queued |
idempotent | true if this is a cache hit — no new email was created |
suppressed_recipients | Addresses filtered out due to suppression. Omitted if none |
Idempotency
| Scenario | Result |
|---|---|
| Same key + same payload | Returns original response with "idempotent": true. No new email sent |
| Same key + different payload | 409 Conflict |
| No key provided | Auto-generated UUID. No deduplication |
Errors
| Status | Code | Cause |
|---|---|---|
400 | DOMAIN_NOT_VERIFIED | Sending from an unverified domain |
401 | UNAUTHORIZED | Missing or invalid API key |
409 | CONFLICT | Idempotency key reused with different payload |
422 | VALIDATION_ERROR | Invalid body — missing fields or bad email format |
429 | RATE_LIMIT_EXCEEDED | Too many requests — see rate limits |
Get send status
GET /api/v1/send/:id/status
Authentication
AcceptsX-API-Key or Authorization: Bearer (JWT).
Request
curl https://api.numonic.com/api/v1/send/550e8400-e29b-41d4-a716-446655440000/status \
-H "X-API-Key: nmc_live_YOUR_API_KEY"
Response 200
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"status": "sent",
"from_address": "noreply@yourapp.com",
"to_addresses": ["user@example.com"],
"subject": "Your order is confirmed",
"queued_at": "2026-04-09T10:30:00.000Z",
"sent_at": "2026-04-09T10:30:05.000Z",
"provider_message_id": "0100018b-1234-5678-90ab-cdefghij",
"error_code": null,
"error_message": null
}
Response fields
| Field | Description |
|---|---|
id | UUID for this send |
status | Current status — see statuses |
from_address | Sender address |
to_addresses | All recipient addresses |
subject | Subject line |
queued_at | When the send was queued |
sent_at | When the send was handed to SES. null until sent |
provider_message_id | SES message ID. null until sent |
error_code | Machine-readable error. null if no error |
error_message | Human-readable error. null if no error |
Errors
| Status | Code | Cause |
|---|---|---|
401 | UNAUTHORIZED | Missing or invalid credentials |
404 | NOT_FOUND | No send found with this ID for your account |
Statuses
| Status | Description |
|---|---|
queued | Accepted and queued for delivery |
processing | Being processed by the email worker |
sent | Handed to SES |
delivered | Confirmed received by the recipient’s mail server |
bounced | Rejected by recipient’s mail server. Hard bounces automatically add the address to your suppression list |
complained | Recipient filed a spam complaint. Address is automatically suppressed |
suppressed | All recipients were suppressed before the send went out |
failed | Failed. See error_code and error_message for details |
Rate limits
| Window | Limit |
|---|---|
| Per second (burst) | 3 requests |
| Per 10 seconds | 20 requests |
| Per minute | 100 requests |
429 Rate Limit Exceeded. Back off and retry.