# Introduction

> Nofy is Encipher's notification API. Send Email, WhatsApp, Push and SMS through one handoff, then know exactly what happened to every recipient.

Your product hands Nofy one message: who it is for, which channels, what
to say. Nofy fans it out to one delivery per recipient, sends through the
right provider, retries what fails for transient reasons, and tells you the
outcome through signed callbacks and a pull API you can reconcile against.

### Quickstart
Get a token, provision a tenant and send your first SMS in about five minutes.
### API reference
Every endpoint with typed parameters and request and response examples.
### Sending on v2
The message shape for each channel: SMS, Email, Push and WhatsApp templates.
### Callbacks
Signed status posts for every delivery, and how to verify them.

## How it works

### Authenticate your backend
Exchange your client id and secret for a Bearer token with the
client-credentials grant. Every send is attributed to your application.
### Register your customers
Each of your customers becomes a **tenant**, keyed by your own id for it.
Quotas, credentials and alerts can be set per tenant.
### Hand off a message
`POST /v2/messages` with an `Idempotency-Key` header. Retrying with the same
key never sends twice, so your own retries are always safe.
### Track every delivery
Nofy answers `202` straight away and works in the background. Follow each
delivery through callbacks, or pull `GET /v2/deliveries`.

## Channels

| Channel    | Provider               | You send                                   |
|------------|------------------------|--------------------------------------------|
| `sms`      | Beem                   | Plain text to E.164 phone numbers          |
| `email`    | SMTP                   | Subject, text and optional HTML with inline images |
| `push`     | Firebase Cloud Messaging | Title, body and data to *your user ids*  |
| `whatsapp` | Meta Cloud API         | Approved templates with parameters         |

!!! tip "One message, several channels"
    A single handoff can carry an entry per channel, for example an SMS and
    an email for the same event. Each recipient on each channel gets its own
    delivery with its own status.

## Guarantees

### Idempotent sends
Every `POST /v2/messages` carries an `Idempotency-Key`. Replaying a key returns
the original `202` response instead of sending again.
### Automatic retries
Transient failures retry on a ladder of five attempts. Permanent rejections
fail at once with the provider's reason. See [Errors & retries](errors).
### Honest delivery state
`202` means accepted, not delivered. Each delivery moves from `pending` to
`sent` or `failed`, and WhatsApp adds delivered and read receipts.
### Quotas that isolate customers
A tenant over its daily allowance gets `429` while your other tenants keep
sending. See [Tenants & quotas](tenants-quotas).

## Get help

Write to [support@encipher.co.tz](mailto:support@encipher.co.tz) for
credentials, sender ids, WhatsApp template approvals or anything these docs
do not answer.