Quickstart

Prerequisites

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

1. Get your API key

Log in to the Numonic dashboard
Go to Settings → API Keys
Click Create API Key
Choose type live, give it a name (e.g. “Production Key”)
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.

Go to Domains → Add Domain
Enter your domain (e.g. yourapp.com)
Numonic returns DNS records to add at your registrar — a TXT record for ownership verification and CNAME records for DKIM signing
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

API Reference: Sends — full send endpoint docs
API Reference: Domains — domain registration and verification
API Reference: API Keys — manage API keys
API Reference: Suppression — view and manage your suppression list
API Reference: Events — query delivery events

​Quickstart

​Prerequisites

​1. Get your API key

​2. Verify a domain

​3. Send your first email

​4. Read the response

​5. Check status

​6. Prevent duplicate sends

​Next steps