Skip to main content

​
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

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."
  }'
All fields: 
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

ParameterTypeRequiredDescription
fromstringYesSender email. Must use a verified domain in your account
tostring[]YesRecipient addresses. Array, minimum 1
subjectstringYesEmail subject
htmlstringYes*HTML body. At least one of html or text required
textstringYes*Plain text body
ccstring[]NoCC recipients
bccstring[]NoBCC recipients
reply_tostringNoReply-to address
idempotency_keystringNoDeduplication 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
}
If recipients were suppressed: 
{
  "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

FieldDescription
idUUID for this send. Use to query status
statusCurrent status — see statuses
idempotency_keyKey used for this send
queued_atISO 8601 timestamp when queued
idempotenttrue if this is a cache hit — no new email was created
suppressed_recipientsAddresses filtered out due to suppression. Omitted if none

​
Idempotency

ScenarioResult
Same key + same payloadReturns original response with "idempotent": true. No new email sent
Same key + different payload409 Conflict
No key providedAuto-generated UUID. No deduplication

​
Errors

StatusCodeCause
400DOMAIN_NOT_VERIFIEDSending from an unverified domain
401UNAUTHORIZEDMissing or invalid API key
409CONFLICTIdempotency key reused with different payload
422VALIDATION_ERRORInvalid body — missing fields or bad email format
429RATE_LIMIT_EXCEEDEDToo many requests — see 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

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

FieldDescription
idUUID for this send
statusCurrent status — see statuses
from_addressSender address
to_addressesAll recipient addresses
subjectSubject line
queued_atWhen the send was queued
sent_atWhen the send was handed to SES. null until sent
provider_message_idSES message ID. null until sent
error_codeMachine-readable error. null if no error
error_messageHuman-readable error. null if no error

​
Errors

StatusCodeCause
401UNAUTHORIZEDMissing or invalid credentials
404NOT_FOUNDNo send found with this ID for your account

​
Statuses

StatusDescription
queuedAccepted and queued for delivery
processingBeing processed by the email worker
sentHanded to SES
deliveredConfirmed received by the recipient’s mail server
bouncedRejected by recipient’s mail server. Hard bounces automatically add the address to your suppression list
complainedRecipient filed a spam complaint. Address is automatically suppressed
suppressedAll recipients were suppressed before the send went out
failedFailed. See error_code and error_message for details

​
Rate limits

WindowLimit
Per second (burst)3 requests
Per 10 seconds20 requests
Per minute100 requests
When rate limited, you’ll receive 429 Rate Limit Exceeded. Back off and retry.