> ## 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.

# Quickstart

> Go from zero to your first transactional email in minutes

# 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:

```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":    "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:**

```javascript theme={null}
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:

```json theme={null}
{
  "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`:

```json theme={null}
{
  "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

```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"
```

```json theme={null}
{
  "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:

```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":            "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](/api-reference/sends) — full send endpoint docs
* [API Reference: Domains](/api-reference/domains) — domain registration and verification
* [API Reference: API Keys](/api-reference/api-keys) — manage API keys
* [API Reference: Suppression](/api-reference/suppression) — view and manage your suppression list
* [API Reference: Events](/api-reference/events) — query delivery events