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

# Introduction

> What Numonic is and why it exists

Numonic is an email delivery API built on AWS SES. It sits between your application and SES and adds what SES doesn't give you natively: pre-flight validation, automatic suppression management, delivery event tracking, and a permanent record for every send.

## The core idea

When you send an email through Numonic, you get back an ID. That ID is a durable reference — you can query the status of that send at any point in time, from `queued` all the way through `delivered`, `bounced`, or `complained`.

```bash theme={null}
GET /api/v1/send/550e8400-e29b-41d4-a716-446655440000/status
```

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "bounced",
  "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:02.000Z",
  "provider_message_id": "0100018b-1234-5678-90ab-cdef",
  "error_code": null,
  "error_message": null
}
```

## What Numonic does

**Before sending**, every request goes through pre-flight evaluation:

* **Suppression check** — suppressed recipients are filtered out before the send goes out. The rest still go. Suppressed addresses are listed in the response.
* **Domain verification** — the `from` address must use a domain registered and verified in your Numonic account.

**On send**, Numonic queues the email and returns `202 Accepted` immediately. The email is processed asynchronously.

**After sending**, SES delivery events (deliveries, bounces, complaints) are ingested automatically. Hard bounces and spam complaints add addresses to your suppression list so you don't have to manage that yourself.

## What Numonic is not

Numonic is not a marketing email platform. There are no templates, campaigns, or contact lists. It's infrastructure for developers who need reliable transactional email with full delivery visibility.

## Authentication

Two forms of authentication are supported:

| Method  | Header                      | Use case                               |
| ------- | --------------------------- | -------------------------------------- |
| API Key | `X-API-Key: nmc_live_...`   | Server-side sending                    |
| JWT     | `Authorization: Bearer ...` | Dashboard sessions, account management |

Send endpoints accept both. Domain, API key management, events, and suppression endpoints require JWT.

## Base URL

```
https://api.numonic.com
```

All endpoints are prefixed with `/api/v1/`.