',
to,
subject: 'Welcome to Acme',
html: 'Your account is ready. Sign in.
',
text: 'Your account is ready. Sign in at https://yourdomain.com/login',
tags: [{ name: 'category', value: 'welcome' }],
});
console.info('Welcome email accepted', { emailId: email.id, status: email.status });
return { ok: true, message: 'Check your inbox.' };
} catch (error) {
if (error instanceof APIError) {
console.error('Welcome email rejected', { status: error.status, code: error.code, requestId: error.requestId });
} else {
console.error('Welcome email failed', error);
}
return { ok: false, message: 'The email could not be sent. Try again in a minute.' };
}
}
```
The `from` address must use your verified domain. Sending both `html` and `text` gives mail clients that block HTML a readable fallback.
The API answers `202 Accepted`. The SDK returns the email `id` (prefixed `em_`) and its `status`, which is `queued`: Nuntly has accepted the email and delivers it after the call returns. Delivery is reported later through events, covered in [Observe what happened](#observe-what-happened).
Call the action from a Client Component with React's `useActionState` hook, as in the [Next.js forms guide](https://nextjs.org/docs/app/guides/forms):
```tsx app/signup/signup-form.tsx theme={null}
'use client';
import { useActionState } from 'react';
import { sendWelcomeEmail, type SendState } from '@/app/actions/send-welcome-email';
const initialState: SendState = { ok: false, message: '' };
export function SignupForm() {
const [state, formAction, pending] = useActionState(sendWelcomeEmail, initialState);
return (
);
}
```
```tsx app/signup/page.tsx theme={null}
import { SignupForm } from './signup-form';
export default function SignupPage() {
return ;
}
```
Run `npm run dev`, open `/signup`, and submit your own address. The email arrives in your inbox, and its `em_` ID appears in your server logs.
### Server Action or Route Handler
Use a Server Action when your own UI triggers the send. Use a Route Handler (`app/**/route.ts`) when the trigger comes from outside your UI: a cron job, a queue worker, or another service calling your app over HTTP. Both run the same `nuntly.emails.send` call.
| | Server Action | Route Handler |
| - | - | - |
| Triggered by | Your forms and Client Components | Any HTTP client |
| File | `'use server'` module, for example `app/actions/*.ts` | `app/**/route.ts` |
| Typical use | Signup, password reset, invitation forms | Webhooks, cron jobs, service-to-service calls |
| Access control | Check the session inside the action | Authenticate every request |
Route Handlers are public HTTP endpoints ([Next.js backend for frontend guide](https://nextjs.org/docs/app/guides/backend-for-frontend)). Never expose a Route Handler that reads a recipient address from the request body and sends to it without authentication: anyone who finds the URL can send email from your domain. An exported Server Action is also reachable with a direct POST request ([Next.js data security guide](https://nextjs.org/docs/app/guides/data-security)). Check the session inside any action that sends on behalf of a signed-in user.
## Observe what happened
A `202` confirms that Nuntly accepted the email. Delivery comes afterwards, and two places report it: the dashboard, for one email at a time, and webhooks, for your code.
### Email timeline in the dashboard
In the dashboard, open **Emails**, select the email, then click **Email Timeline**. The timeline lists every event recorded for that email with its timestamp. A typical send goes through `queued`, `processed`, `sending` and `sent`, then reaches an outcome such as `delivered`, `bounced`, `rejected` or `failed`.
A `deliveryDelayed` event marks a delay in delivery to the recipient. `opened` and `clicked` events appear when [open and click tracking](/docs/guides/sending-domains#enable-open-and-click-tracking) is enabled on the domain. Events are kept for 30 days by default; see [data retention](/docs/guides/data-retention).
### Receive webhooks in a Route Handler
Receiving webhooks is a job for a Route Handler, because Nuntly calls your app over HTTP. Each request carries a `webhook-signature` header: an HMAC-SHA256 signature of the timestamp and the raw body, computed with your webhook's signing secret. Recomputing it proves the request came from Nuntly and was not altered.
Create a webhook in the dashboard (see [webhooks](/docs/guides/webhooks)) that points to `https://yourapp.com/api/webhooks/nuntly`, and select the events you need, for example `email.delivered`, `email.bounced` and `email.complained`.
Copy the signing secret, which starts with `whsec_`, into `.env.local`.
```bash .env.local theme={null}
NUNTLY_WEBHOOK_SECRET=whsec_your_signing_secret
```
The SDK's `verifyWebhook` function checks the signature and returns a typed event.
```typescript app/api/webhooks/nuntly/route.ts theme={null}
import { verifyWebhook, WebhookVerificationError } from '@nuntly/sdk';
export async function POST(request: Request) {
const payload = await request.text();
const signature = request.headers.get('webhook-signature') ?? '';
let event;
try {
event = await verifyWebhook(payload, signature, process.env.NUNTLY_WEBHOOK_SECRET ?? '');
} catch (error) {
if (error instanceof WebhookVerificationError) {
return new Response('Invalid signature', { status: 401 });
}
throw error;
}
switch (event.type) {
case 'email.delivered':
console.info('Email delivered', { emailId: event.data.id, eventId: event.id });
break;
case 'email.bounced':
console.warn('Email bounced', {
emailId: event.data.id,
bounceType: event.data.bounce.bounceType,
});
break;
case 'email.complained':
console.warn('Spam complaint', { emailId: event.data.id });
break;
default:
console.info('Unhandled event', { type: event.type, eventId: event.id });
}
return Response.json({ received: true });
}
```
The handler relies on four details:
* **The raw body.** The signature covers the exact bytes Nuntly sent, so read them with `request.text()`. Parsing with `request.json()` and serializing again breaks verification. Route Handlers expose the raw body without any `bodyParser` configuration.
* **A `401` on a bad signature.** `verifyWebhook` throws `WebhookVerificationError` when the signature does not match, the header is malformed, or the timestamp is more than 5 minutes away from the current time, which blocks replayed requests.
* **Typed events.** The event is a union typed on `event.type`, so inside `case 'email.bounced'` TypeScript knows that `event.data.bounce` exists. A `Permanent` bounce type means the address cannot receive mail: stop sending to it.
* **A fast `2xx`.** Any response other than `2xx` counts as a failed delivery. Respond first and move slow work out of the request path.
Nuntly retries failed deliveries and records each attempt; see [webhook observability](/docs/guides/observability-webhooks). After an outage on your side, you can replay a missed event from the dashboard or with `POST /webhooks/{id}/events/{eventId}/replay`.
Because of retries and replays, the same event can arrive more than once. Deduplicate on the root `id` (prefixed `evt_`). Do not use `data.id`: it is the email ID, shared by every event of that email. A unique constraint on a table of processed event IDs is enough.
For every event type and payload, see [sending events](/docs/guides/sending-webhooks).
## Production notes
### Idempotency keys
The SDK sends an `Idempotency-Key` header on every `emails.send` call. It generates a UUID v4 and reuses it across its own automatic retries, so a retry after a `503` cannot send a second email.
That automatic key does not cover a Server Action that runs twice: a double click, a browser resubmitting after a dropped connection, a server restart during the request. Each run is a new `send` call with a new random key. Derive the key from your own data to make the operation itself idempotent:
```typescript theme={null}
await nuntly.emails.send(
{
from: 'Acme ',
to: user.email,
subject: 'Welcome to Acme',
html: 'Your account is ready.
',
},
{ idempotencyKey: `welcome-${user.id}` },
);
```
Nuntly keeps a key for 24 hours, and a key must be 8 to 255 characters long. A repeat with the same key and the same body returns the original response with an `Idempotent-Replayed: true` header. The same key with a different body returns `409 idempotency_key_payload_mismatch`. See [idempotency keys](/docs/guides/idempotency) for key strategies.
### Retries
The SDK retries timeouts and `408`, `409`, `429`, `500`, `502`, `503` and `504` responses, up to 2 times by default with exponential backoff from 500 ms to 8 seconds, and honors the `Retry-After` header. Change the policy with the `maxRetries` and `retry` client options.
### Error handling
An error that reaches your `catch` block is either a client error that a retry would not fix, or a failure that outlasted the retries. Every API error is an `APIError` subclass with `status`, `code` and `requestId`.
| Status | Code | Action |
| - | - | - |
| `400` | `domain_not_verified` | Finish DNS verification for the `from` domain. |
| `401` | | Check `NUNTLY_API_KEY` in this environment. |
| `404` | `domain_not_found` | Add the `from` domain to your account. |
| `409` | `idempotency_key_payload_mismatch` | Use a new key for a different email. |
| `429`, `500`, `502`, `503`, `504` | | Already retried by the SDK. Show a "try again" message. |
Return a generic message to the browser, as the Server Action above does, and log the `requestId` so a failed request can be traced. See [errors](/docs/api-reference/errors).
### Separate environments
Use one API key per environment: `.env.local` for development, your hosting provider's environment settings for preview and production. Revoking a leaked development key then has no effect on production. You can restrict a key to sending only; see [API keys](/docs/guides/api-keys).
### What not to log
Recipient email addresses are personal data, and logs are a separate store with their own retention and access rules.
* Log the `em_` email ID, the `evt_` event ID and the `requestId`. They identify the email without identifying the person.
* Do not log `to`, `from`, `subject`, the HTML body, or a full webhook payload. A `console.log(event)` in the webhook handler writes a recipient address to your logs on every delivery.
* To investigate a support request, take the email ID from your logs and open the email in the dashboard.
## Next steps
Signature verification details and webhook best practices
Payload reference for every sending event
Key formats, strategies, and error codes
Install and configure the Nuntly SDKs
## Other frameworks
Send from an Express route and verify webhooks on the raw body
Inject the client as a provider and send from a service
Use the Spring Boot starter on Java 21
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.