# notify-gateway

> One REST API to reach your users on any channel — WhatsApp, SMS, Telegram, and email — designed to be hard to get wrong: dead-simple to call, and reliable by default.

notify-gateway exists so that a single `POST` reliably reaches a person. Two promises:

- **Accepted means delivered.** The moment the API returns `202`, the gateway owns delivery — every message is persisted and retried with exponential backoff until it succeeds, or is dead-lettered and reported back. Nothing is silently dropped.
- **Radically simple.** One obvious endpoint per channel, the smallest possible body (`to`, `message`), one API key. A newcomer makes their first send in under a minute from a copy-paste `curl` — and an AI agent can wire it up from this file alone.

## Docs

- [Interactive API reference (OpenAPI / Swagger)](https://api.notifygw.com/docs): every endpoint, request/response schema, and live "try it".
- [Dashboard & API keys](https://notifygw.com/dashboard): sign up, create a Bearer API key (`ngw_...`), connect channels.

## API

- [Send SMS](https://api.notifygw.com/docs#/send/send_sms): `POST /api/v1/sms` with `{"to":"+15551234567","message":"..."}`.
- [Send WhatsApp](https://api.notifygw.com/docs#/send/send_whatsapp): `POST /api/v1/whatsapp` with `{"to","message","media_url?"}`.
- [Send Telegram](https://api.notifygw.com/docs#/send/send_telegram): `POST /api/v1/telegram` with `{"to","message"}`.
- [Send Email](https://api.notifygw.com/docs#/send/send_email): `POST /api/v1/email` with `{"to","subject","message"}`.
- [Delivery status](https://api.notifygw.com/docs#/messages): `GET /api/v1/messages/{outbox_id}` returns `status` = scheduled | queued | sent | failed.

## Notes for agents

- Authentication: every call needs `Authorization: Bearer <key>` (create a key in the dashboard).
- All sends return `202 {"status":"queued","outbox_id":<id>}`. Sending is asynchronous — `202` means accepted, not delivered; poll the delivery-status endpoint to confirm.
- Errors are JSON `{"detail":"..."}` with a real HTTP status (400/404/409/422/503). Rate limits return `429` with `Retry-After`. Phone numbers should be E.164.
- Every send endpoint accepts an optional `Idempotency-Key` header — retrying with the same key never sends twice (exactly-once per account; the original `outbox_id` is returned).
- The unified `POST /api/v1/messages/send` accepts an optional `scheduled_for` (ISO-8601 with timezone) to schedule a send for later (`status` = scheduled until due).