Skip to main content

​
Quickstart

​
Prerequisites

  • A Numonic account
  • A domain you own with access to DNS settings

​
1. Get your API key

  1. Log in to the Numonic dashboard
  2. Go to Settings → API Keys
  3. Click Create API Key
  4. Choose type live, give it a name (e.g. “Production Key”)
  5. Copy the key immediately — it’s only shown once
Your key looks like: nmc_live_abc123def456...

​
2. Verify a domain

Before sending, you need to verify ownership of the domain you’ll send from.
  1. Go to Domains → Add Domain
  2. Enter your domain (e.g. yourapp.com)
  3. Numonic returns DNS records to add at your registrar — a TXT record for ownership verification and CNAME records for DKIM signing
  4. Add those records at your DNS provider (Cloudflare, Route 53, Namecheap, etc.)
Verification typically completes within a few minutes but can take up to 72 hours depending on DNS propagation. The dashboard shows real-time status.

​
3. Send your first email

Once your domain shows Verified, you’re ready to send: 
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":    "hello@yourapp.com",
    "to":      ["recipient@example.com"],
    "subject": "Hello from Numonic",
    "html":    "<h1>It works!</h1><p>Your first transactional email via Numonic.</p>",
    "text":    "It works! Your first transactional email via Numonic."
  }'
Node.js: 
const response = await fetch('https://api.numonic.com/api/v1/send', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'nmc_live_YOUR_API_KEY',
  },
  body: JSON.stringify({
    from: 'hello@yourapp.com',
    to: ['recipient@example.com'],
    subject: 'Hello from Numonic',
    html: '<h1>It works!</h1><p>Your first transactional email via Numonic.</p>',
  }),
});

const { id, status } = await response.json();
console.log(`Email ${id} is ${status}`);

​
4. Read the response

Numonic returns 202 Accepted immediately: 
{
  "id":              "550e8400-e29b-41d4-a716-446655440000",
  "status":          "queued",
  "idempotency_key": "auto-generated-uuid",
  "queued_at":       "2026-04-09T10:30:00.000Z",
  "idempotent":      false
}
Save the id — use it to check delivery status. If any recipients were on your suppression list, they’re filtered out before the send goes out and listed in suppressed_recipients: 
{
  "id":                    "550e8400-e29b-41d4-a716-446655440000",
  "status":                "queued",
  "idempotency_key":       "auto-generated-uuid",
  "queued_at":             "2026-04-09T10:30:00.000Z",
  "idempotent":            false,
  "suppressed_recipients": ["bounced@example.com"]
}

​
5. Check status

curl https://api.numonic.com/api/v1/send/550e8400-e29b-41d4-a716-446655440000/status \
  -H "X-API-Key: nmc_live_YOUR_API_KEY"

{
  "id":                  "550e8400-e29b-41d4-a716-446655440000",
  "status":              "sent",
  "from_address":        "hello@yourapp.com",
  "to_addresses":        ["recipient@example.com"],
  "subject":             "Hello from Numonic",
  "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
}
Status lifecycle: queued → processing → sent → delivered | bounced | complained | failed

​
6. Prevent duplicate sends

Pass an idempotency_key to protect against retries sending duplicate emails: 
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":            "hello@yourapp.com",
    "to":              ["recipient@example.com"],
    "subject":         "Order #12345 Confirmation",
    "html":            "<p>Your order has been confirmed.</p>",
    "idempotency_key": "order-12345-confirmation"
  }'
  • Same key + same payload → returns original response ("idempotent": true), no new email created
  • Same key + different payload → 409 Conflict
  • No key → auto-generated, no deduplication

​
Next steps