> ## Documentation Index > Fetch the complete documentation index at: https://docs.numonic.com/llms.txt > Use this file to discover all available pages before exploring further. # Sends > Send emails and track their delivery status # 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 ``` Queues an email for delivery. Returns `202 Accepted` immediately. ### Authentication Accepts `X-API-Key` or `Authorization: Bearer` (JWT). ### Request ```bash theme={null} 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": "

Thanks for your order.

", "text": "Thanks for your order." }' ``` **All fields:** ```bash theme={null} 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": "

Order Confirmed

Your order #12345 has been confirmed.

", "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` ```json theme={null} { "id": "550e8400-e29b-41d4-a716-446655440000", "status": "queued", "idempotency_key": "order-12345-confirmation", "queued_at": "2026-04-09T10:30:00.000Z", "idempotent": false } ``` If recipients were suppressed: ```json theme={null} { "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](#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](#rate-limits) | *** ## Get send status ``` GET /api/v1/send/:id/status ``` Returns the current status of a send by its ID. ### Authentication Accepts `X-API-Key` or `Authorization: Bearer` (JWT). ### Request ```bash theme={null} 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` ```json theme={null} { "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](#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 | When rate limited, you'll receive `429 Rate Limit Exceeded`. Back off and retry.