npm - @eusend_dev/sdk - Versions diffs - 0.3.2 → 0.3.3 - Mend

@eusend_dev/sdk 0.3.2 → 0.3.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/README.md CHANGED Viewed

@@ -1,568 +1,568 @@
-# eusend
-Official Node.js SDK for the [Eusend](https://eusend.dev) API — the EU-native transactional email platform.
-```bash
-npm install @eusend_dev/sdk
-# or
-bun add @eusend_dev/sdk
-```
----
-## Getting started
-```ts
-import { Eusend } from '@eusend_dev/sdk'
-const client = new Eusend('eu_live_...')
-```
-Your API key can also be set via the `EUSEND_API_KEY` environment variable, in which case the constructor argument can be omitted:
-```ts
-const client = new Eusend()
-```
----
-## Emails
-### Send an email
-```ts
-const { data, error } = await client.emails.send({
-  from: 'you@yourdomain.com',
-  to: 'user@example.com',
-  subject: 'Hello',
-  html: '<p>Hello world</p>',
-  text: 'Hello world',
-})
-console.log(data?.id) // em_...
-```
-#### Options
-| Field | Type | Description |
-|-------|------|-------------|
-| `from` | `string` | Sender email address |
-| `to` | `string \| string[]` | Recipient(s) |
-| `cc` | `string \| string[]` | CC recipient(s) |
-| `bcc` | `string \| string[]` | BCC recipient(s) |
-| `replyTo` | `string \| string[]` | Reply-to address(es) |
-| `subject` | `string` | Email subject |
-| `html` | `string` | HTML body |
-| `text` | `string` | Plain text body |
-| `templateId` | `string` | ID of a saved template |
-| `variables` | `Record<string, unknown>` | Template variable substitutions |
-| `headers` | `Record<string, string>` | Custom email headers |
-| `trackOpens` | `boolean` | Track open events (default: `true`) |
-| `trackClicks` | `boolean` | Track click events (default: `true`) |
-At least one of `html`, `react`, `text`, or `templateId` is required.
-### Send with React Email
-Pass a React Email component via the `react` field. The SDK renders it to HTML locally before sending — the JSX source never travels over the wire.
-```tsx
-import { Eusend } from '@eusend_dev/sdk'
-import { WelcomeEmail } from './emails/welcome'
-const client = new Eusend()
-await client.emails.send({
-  from: 'hello@yourdomain.com',
-  to: 'user@example.com',
-  subject: 'Welcome',
-  react: <WelcomeEmail name="Jane" />,
-})
-```
-Requires `react` and `@react-email/render` as peer dependencies:
-```bash
-npm install react @react-email/render
-```
-If you prefer to render yourself, pass the resulting HTML via `html` instead — useful when you want one rendered template to serve multiple sends.
-### Idempotent sends
-Pass an `idempotencyKey` to safely retry without sending duplicates. If a request with the same key was already accepted, the original email ID is returned.
-```ts
-const { data } = await client.emails.send(
-  {
-    from: 'you@yourdomain.com',
-    to: 'user@example.com',
-    subject: 'Your receipt',
-    html: '<p>Thanks for your order.</p>',
-  },
-  { idempotencyKey: `receipt-${orderId}` },
-)
-```
-### Send a batch
-Up to 100 emails in a single request.
-```ts
-const { data } = await client.emails.batch([
-  {
-    from: 'you@yourdomain.com',
-    to: 'alice@example.com',
-    subject: 'Hello Alice',
-    html: '<p>Hi Alice</p>',
-  },
-  {
-    from: 'you@yourdomain.com',
-    to: 'bob@example.com',
-    subject: 'Hello Bob',
-    html: '<p>Hi Bob</p>',
-  },
-])
-console.log(data?.data) // [{ id: '...' }, { id: '...' }]
-```
-### Retrieve an email
-```ts
-const { data } = await client.emails.get('em_...')
-console.log(data?.status)  // 'delivered'
-console.log(data?.events)  // [{ type: 'sent', ... }, { type: 'delivered', ... }]
-```
-### List emails
-```ts
-const { data } = await client.emails.list({ limit: 20 })
-console.log(data?.data)       // array of emails
-console.log(data?.nextCursor) // pass as cursor to fetch the next page
-```
-#### Filtering
-```ts
-// By status
-await client.emails.list({ status: 'delivered' })
-// By sender
-await client.emails.list({ from: 'you@yourdomain.com' })
-// By recipient
-await client.emails.list({ to: 'user@example.com' })
-// Pagination
-await client.emails.list({ limit: 50, cursor: data.nextCursor })
-```
-Available statuses: `queued` `sending` `sent` `delivered` `bounced` `complained` `suppressed` `failed`
----
-## Domains
-### Add a domain
-```ts
-const { data } = await client.domains.create('yourdomain.com')
-// DNS records to add to your domain
-console.log(data?.dkim)   // { type: 'TXT', name: 'eusend._domainkey.yourdomain.com', value: '...' }
-console.log(data?.spf)    // { type: 'TXT', name: 'yourdomain.com', value: '...' }
-console.log(data?.dmarc)  // { type: 'TXT', name: '_dmarc.yourdomain.com', value: '...' }
-```
-### Verify a domain
-After adding the DNS records, trigger verification:
-```ts
-await client.domains.verify(domainId)
-```
-### List domains
-```ts
-const { data } = await client.domains.list()
-// [{ id, name, status: 'verified', createdAt }]
-```
-### Get a domain
-```ts
-const { data } = await client.domains.get(domainId)
-// { id, name, dkimPublicKey, dkimSelector, status, createdAt, verifiedAt }
-```
-### Delete a domain
-```ts
-await client.domains.delete(domainId)
-```
----
-## API Keys
-### Create an API key
-```ts
-const { data } = await client.apiKeys.create({ name: 'Production' })
-console.log(data?.key) // eu_live_... — only returned once, store it securely
-```
-Pass `testMode: true` to create a sandbox key. Emails sent with a test key are accepted and tracked but never delivered.
-```ts
-const { data } = await client.apiKeys.create({ name: 'Sandbox', testMode: true })
-// data.key → 'eu_test_...'
-```
-### List API keys
-```ts
-const { data } = await client.apiKeys.list()
-// [{ id, name, prefix, testMode, createdAt, lastUsedAt }]
-```
-The full key is never returned after creation — only the prefix (e.g. `eu_live_Lx_e`).
-### Delete an API key
-```ts
-await client.apiKeys.delete(keyId)
-```
----
-## Audiences & Contacts
-### Create an audience
-```ts
-const { data } = await client.audiences.create('Newsletter')
-const audienceId = data!.id
-```
-### List audiences
-```ts
-const { data } = await client.audiences.list()
-// [{ id, name, createdAt, contactCount }]
-```
-### Delete an audience
-```ts
-await client.audiences.delete(audienceId)
-```
-### Add a contact
-```ts
-const { data } = await client.audiences.createContact(audienceId, {
-  email: 'user@example.com',
-  firstName: 'Jane',
-  lastName: 'Smith',
-})
-```
-If a contact with that email already exists in the audience, it will be updated instead.
-### Bulk import contacts
-Up to 1,000 contacts per call. Existing contacts are upserted.
-```ts
-const { data } = await client.audiences.batchCreateContacts(audienceId, {
-  contacts: [
-    { email: 'alice@example.com', firstName: 'Alice' },
-    { email: 'bob@example.com', firstName: 'Bob' },
-  ],
-})
-console.log(data?.count) // 2
-```
-### List contacts
-```ts
-const { data } = await client.audiences.listContacts(audienceId, { limit: 100 })
-// Filter by subscription status
-await client.audiences.listContacts(audienceId, { subscribed: true })
-await client.audiences.listContacts(audienceId, { subscribed: false })
-// Search by email
-await client.audiences.listContacts(audienceId, { search: 'gmail.com' })
-// Pagination
-await client.audiences.listContacts(audienceId, { cursor: data.nextCursor })
-```
-### Get a contact
-```ts
-const { data } = await client.audiences.getContact(audienceId, contactId)
-// { id, audienceId, email, firstName, lastName, status, unsubscribedAt, createdAt, updatedAt }
-```
-### Update a contact
-```ts
-// Update name
-await client.audiences.updateContact(audienceId, contactId, {
-  firstName: 'Janet',
-})
-// Unsubscribe
-await client.audiences.updateContact(audienceId, contactId, {
-  unsubscribed: true,
-})
-// Re-subscribe
-await client.audiences.updateContact(audienceId, contactId, {
-  unsubscribed: false,
-})
-```
-### Delete a contact
-```ts
-await client.audiences.deleteContact(audienceId, contactId)
-```
----
-## Templates
-Templates let you define reusable email layouts with `{{variable}}` placeholders that are substituted at send time.
-### Create a template (HTML)
-```ts
-const { data } = await client.templates.create({
-  name: 'Welcome email',
-  subject: 'Welcome, {{name}}!',
-  html: '<h1>Hi {{name}}</h1><p>Welcome to {{product}}.</p>',
-})
-```
-### Create a template (React Email)
-Pass a React Email component via `react`. The SDK renders it to HTML locally before submitting — the JSX source never travels over the wire.
-```tsx
-import { OrderConfirmation } from './emails/order-confirmation'
-const { data } = await client.templates.create({
-  name: 'Order confirmation',
-  subject: 'Your order {{order_id}} is confirmed',
-  react: <OrderConfirmation />,
-})
-```
-Use `{{variable}}` placeholders anywhere in your React component; they pass through to the rendered HTML and are substituted at send time when you provide `variables`. If you'd rather render yourself, pass `html` instead.
-### Send using a template
-```ts
-await client.emails.send({
-  from: 'you@yourdomain.com',
-  to: 'user@example.com',
-  templateId: data!.id,
-  variables: {
-    first_name: 'Jane',
-    order_id: 'ORD-1234',
-  },
-})
-```
-### List, get, update, delete
-```ts
-await client.templates.list()
-await client.templates.get(templateId)
-await client.templates.update(templateId, { name: 'New name', subject: 'New subject' })
-await client.templates.delete(templateId)
-```
----
-## Webhooks
-Receive real-time events when email statuses change.
-### Create a webhook
-```ts
-const { data } = await client.webhooks.create({
-  url: 'https://yourapp.com/webhooks/eusend',
-  events: ['email.sent', 'email.delivered', 'email.bounced', 'email.complained'],
-})
-console.log(data?.secret) // signing secret — only returned once, store it securely
-```
-Pass `'*'` in the events array to subscribe to all events.
-Available events: `email.sent` `email.delivered` `email.bounced` `email.complained` `email.opened` `email.clicked`
-### Verifying webhook signatures
-Every delivery is signed with HMAC-SHA256. Verify the signature before processing:
-```ts
-import { createHmac, timingSafeEqual } from 'crypto'
-function verifyWebhook(req: Request, secret: string): boolean {
-  const webhookId = req.headers.get('x-webhook-id') ?? ''
-  const timestamp = req.headers.get('x-webhook-timestamp') ?? ''
-  const signature = req.headers.get('x-webhook-signature') ?? ''
-  const body = await req.text()
-  const expected = 'v1,' + createHmac('sha256', secret)
-    .update(`${webhookId}.${timestamp}.${body}`)
-    .digest('base64')
-  return timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
-}
-```
-### List, get, update, delete
-```ts
-await client.webhooks.list()
-await client.webhooks.get(webhookId)    // includes recent deliveries
-await client.webhooks.update(webhookId, { events: ['email.bounced'] })
-await client.webhooks.delete(webhookId)
-```
----
-## Broadcasts
-Send a single email to every contact in an audience.
-### Create a broadcast
-```ts
-const { data } = await client.broadcasts.create({
-  name: 'May newsletter',
-  audienceId: 'aud_...',
-  from: 'Sivert <hello@yourdomain.com>',
-  subject: 'May update',
-  html: '<p>Hi {{first_name}}, here is this month's update...</p>',
-})
-```
-You can also pass a React Email component via `react`, a saved template via `templateId`, or plain HTML. With `react`, the SDK renders to HTML locally before submitting:
-```tsx
-import { MayNewsletter } from './emails/may-newsletter'
-await client.broadcasts.create({
-  name: 'May newsletter',
-  audienceId: 'aud_...',
-  from: 'Sivert <hello@yourdomain.com>',
-  subject: 'May update',
-  react: <MayNewsletter />,
-})
-```
-`{{first_name}}`, `{{last_name}}`, `{{full_name}}`, and `{{email}}` are automatically available per recipient. Custom variables can be defined on the broadcast and are merged with per-recipient data.
-### Send a broadcast
-```ts
-await client.broadcasts.send(broadcastId)
-```
-### Schedule a broadcast
-```ts
-await client.broadcasts.send(broadcastId, {
-  scheduledAt: '2026-06-01T09:00:00.000Z',
-})
-```
-### Cancel a broadcast
-```ts
-await client.broadcasts.cancel(broadcastId)
-```
-### List, get, update, delete
-```ts
-await client.broadcasts.list()
-await client.broadcasts.get(broadcastId)   // includes delivery stats
-await client.broadcasts.update(broadcastId, { subject: 'Updated subject' })
-await client.broadcasts.delete(broadcastId)
-```
----
-## Error handling
-Every method returns `{ data, error, headers }`. On success `error` is `null`; on failure `data` is `null`.
-```ts
-const { data, error } = await client.emails.send({ ... })
-if (error) {
-  console.error(error.name)       // 'MONTHLY_LIMIT_EXCEEDED'
-  console.error(error.message)    // 'Monthly send limit exceeded'
-  console.error(error.statusCode) // 429
-} else {
-  console.log(data.id)
-}
-```
-#### Error codes
-| Code | Status | Description |
-|------|--------|-------------|
-| `UNAUTHORIZED` | 401 | Invalid or missing API key |
-| `FORBIDDEN` | 403 | Action not allowed on your plan |
-| `NOT_FOUND` | 404 | Resource not found |
-| `VALIDATION_ERROR` | 400 | Invalid request body |
-| `CONFLICT` | 409 | Resource already exists |
-| `RATE_LIMITED` | 429 | Too many requests |
-| `MONTHLY_LIMIT_EXCEEDED` | 429 | Monthly send quota reached |
-| `DAILY_LIMIT_EXCEEDED` | 429 | Daily send quota reached (free plan) |
-| `PLAN_LIMIT_EXCEEDED` | 403 | Feature not available on your plan |
-| `DOMAIN_NOT_VERIFIED` | 403 | The sender domain is not verified for your organisation |
-| `ALL_SUPPRESSED` | 422 | All recipients are on the suppression list |
-| `INTERNAL_ERROR` | 500 | Server error |
-| `application_error` | `null` | Network failure — request never reached the server |
----
-## TypeScript
-The SDK is written in TypeScript and ships with full type definitions. All request options, response shapes, and error codes are typed.
-```ts
-import type {
-  SendEmailOptions,
-  Email,
-  EmailStatus,
-  EusendError,
-  EusendResponse,
-} from '@eusend_dev/sdk'
-```
----
-## Requirements
-- Node.js 18 or later (uses the native `fetch` API)
-- An Eusend account and API key — [eusend.dev](https://eusend.dev)
+# eusend
+Official Node.js SDK for the [Eusend](https://eusend.dev) API — the EU-native transactional email platform.
+```bash
+npm install @eusend_dev/sdk
+# or
+bun add @eusend_dev/sdk
+```
+---
+## Getting started
+```ts
+import { Eusend } from '@eusend_dev/sdk'
+const client = new Eusend('eu_live_...')
+```
+Your API key can also be set via the `EUSEND_API_KEY` environment variable, in which case the constructor argument can be omitted:
+```ts
+const client = new Eusend()
+```
+---
+## Emails
+### Send an email
+```ts
+const { data, error } = await client.emails.send({
+  from: 'you@yourdomain.com',
+  to: 'user@example.com',
+  subject: 'Hello',
+  html: '<p>Hello world</p>',
+  text: 'Hello world',
+})
+console.log(data?.id) // em_...
+```
+#### Options
+| Field | Type | Description |
+|-------|------|-------------|
+| `from` | `string` | Sender email address |
+| `to` | `string \| string[]` | Recipient(s). Maximum 50. |
+| `cc` | `string \| string[]` | CC recipient(s). Maximum 50. |
+| `bcc` | `string \| string[]` | BCC recipient(s). Maximum 50. |
+| `replyTo` | `string \| string[]` | Reply-to address(es). Maximum 50. |
+| `subject` | `string` | Email subject |
+| `html` | `string` | HTML body |
+| `text` | `string` | Plain text body |
+| `templateId` | `string` | ID of a saved template |
+| `variables` | `Record<string, unknown>` | Template variable substitutions |
+| `headers` | `Record<string, string>` | Custom email headers |
+| `trackOpens` | `boolean` | Track open events (default: `true`) |
+| `trackClicks` | `boolean` | Track click events (default: `true`) |
+At least one of `html`, `react`, `text`, or `templateId` is required.
+### Send with React Email
+Pass a React Email component via the `react` field. The SDK renders it to HTML locally before sending — the JSX source never travels over the wire.
+```tsx
+import { Eusend } from '@eusend_dev/sdk'
+import { WelcomeEmail } from './emails/welcome'
+const client = new Eusend()
+await client.emails.send({
+  from: 'hello@yourdomain.com',
+  to: 'user@example.com',
+  subject: 'Welcome',
+  react: <WelcomeEmail name="Jane" />,
+})
+```
+Requires `react` and `@react-email/render` as peer dependencies:
+```bash
+npm install react @react-email/render
+```
+If you prefer to render yourself, pass the resulting HTML via `html` instead — useful when you want one rendered template to serve multiple sends.
+### Idempotent sends
+Pass an `idempotencyKey` to safely retry without sending duplicates. If a request with the same key was already accepted, the original email ID is returned.
+```ts
+const { data } = await client.emails.send(
+  {
+    from: 'you@yourdomain.com',
+    to: 'user@example.com',
+    subject: 'Your receipt',
+    html: '<p>Thanks for your order.</p>',
+  },
+  { idempotencyKey: `receipt-${orderId}` },
+)
+```
+### Send a batch
+Up to 100 emails in a single request.
+```ts
+const { data } = await client.emails.batch([
+  {
+    from: 'you@yourdomain.com',
+    to: 'alice@example.com',
+    subject: 'Hello Alice',
+    html: '<p>Hi Alice</p>',
+  },
+  {
+    from: 'you@yourdomain.com',
+    to: 'bob@example.com',
+    subject: 'Hello Bob',
+    html: '<p>Hi Bob</p>',
+  },
+])
+console.log(data?.data) // [{ id: '...' }, { id: '...' }]
+```
+### Retrieve an email
+```ts
+const { data } = await client.emails.get('em_...')
+console.log(data?.status)  // 'delivered'
+console.log(data?.events)  // [{ type: 'sent', ... }, { type: 'delivered', ... }]
+```
+### List emails
+```ts
+const { data } = await client.emails.list({ limit: 20 })
+console.log(data?.data)       // array of emails
+console.log(data?.nextCursor) // pass as cursor to fetch the next page
+```
+#### Filtering
+```ts
+// By status
+await client.emails.list({ status: 'delivered' })
+// By sender
+await client.emails.list({ from: 'you@yourdomain.com' })
+// By recipient
+await client.emails.list({ to: 'user@example.com' })
+// Pagination
+await client.emails.list({ limit: 50, cursor: data.nextCursor })
+```
+Available statuses: `queued` `sending` `sent` `delivered` `bounced` `complained` `suppressed` `failed`
+---
+## Domains
+### Add a domain
+```ts
+const { data } = await client.domains.create('yourdomain.com')
+// DNS records to add to your domain
+console.log(data?.dkim)   // { type: 'TXT', name: 'eusend._domainkey.yourdomain.com', value: '...' }
+console.log(data?.spf)    // { type: 'TXT', name: 'yourdomain.com', value: '...' }
+console.log(data?.dmarc)  // { type: 'TXT', name: '_dmarc.yourdomain.com', value: '...' }
+```
+### Verify a domain
+After adding the DNS records, trigger verification:
+```ts
+await client.domains.verify(domainId)
+```
+### List domains
+```ts
+const { data } = await client.domains.list()
+// [{ id, name, status: 'verified', createdAt }]
+```
+### Get a domain
+```ts
+const { data } = await client.domains.get(domainId)
+// { id, name, dkimPublicKey, dkimSelector, status, createdAt, verifiedAt }
+```
+### Delete a domain
+```ts
+await client.domains.delete(domainId)
+```
+---
+## API Keys
+### Create an API key
+```ts
+const { data } = await client.apiKeys.create({ name: 'Production' })
+console.log(data?.key) // eu_live_... — only returned once, store it securely
+```
+Pass `testMode: true` to create a sandbox key. Emails sent with a test key are accepted and tracked but never delivered.
+```ts
+const { data } = await client.apiKeys.create({ name: 'Sandbox', testMode: true })
+// data.key → 'eu_test_...'
+```
+### List API keys
+```ts
+const { data } = await client.apiKeys.list()
+// [{ id, name, prefix, testMode, createdAt, lastUsedAt }]
+```
+The full key is never returned after creation — only the prefix (e.g. `eu_live_Lx_e`).
+### Delete an API key
+```ts
+await client.apiKeys.delete(keyId)
+```
+---
+## Audiences & Contacts
+### Create an audience
+```ts
+const { data } = await client.audiences.create('Newsletter')
+const audienceId = data!.id
+```
+### List audiences
+```ts
+const { data } = await client.audiences.list()
+// [{ id, name, createdAt, contactCount }]
+```
+### Delete an audience
+```ts
+await client.audiences.delete(audienceId)
+```
+### Add a contact
+```ts
+const { data } = await client.audiences.createContact(audienceId, {
+  email: 'user@example.com',
+  firstName: 'Jane',
+  lastName: 'Smith',
+})
+```
+If a contact with that email already exists in the audience, it will be updated instead.
+### Bulk import contacts
+Up to 1,000 contacts per call. Existing contacts are upserted.
+```ts
+const { data } = await client.audiences.batchCreateContacts(audienceId, {
+  contacts: [
+    { email: 'alice@example.com', firstName: 'Alice' },
+    { email: 'bob@example.com', firstName: 'Bob' },
+  ],
+})
+console.log(data?.count) // 2
+```
+### List contacts
+```ts
+const { data } = await client.audiences.listContacts(audienceId, { limit: 100 })
+// Filter by subscription status
+await client.audiences.listContacts(audienceId, { subscribed: true })
+await client.audiences.listContacts(audienceId, { subscribed: false })
+// Search by email
+await client.audiences.listContacts(audienceId, { search: 'gmail.com' })
+// Pagination
+await client.audiences.listContacts(audienceId, { cursor: data.nextCursor })
+```
+### Get a contact
+```ts
+const { data } = await client.audiences.getContact(audienceId, contactId)
+// { id, audienceId, email, firstName, lastName, status, unsubscribedAt, createdAt, updatedAt }
+```
+### Update a contact
+```ts
+// Update name
+await client.audiences.updateContact(audienceId, contactId, {
+  firstName: 'Janet',
+})
+// Unsubscribe
+await client.audiences.updateContact(audienceId, contactId, {
+  unsubscribed: true,
+})
+// Re-subscribe
+await client.audiences.updateContact(audienceId, contactId, {
+  unsubscribed: false,
+})
+```
+### Delete a contact
+```ts
+await client.audiences.deleteContact(audienceId, contactId)
+```
+---
+## Templates
+Templates let you define reusable email layouts with `{{variable}}` placeholders that are substituted at send time.
+### Create a template (HTML)
+```ts
+const { data } = await client.templates.create({
+  name: 'Welcome email',
+  subject: 'Welcome, {{name}}!',
+  html: '<h1>Hi {{name}}</h1><p>Welcome to {{product}}.</p>',
+})
+```
+### Create a template (React Email)
+Pass a React Email component via `react`. The SDK renders it to HTML locally before submitting — the JSX source never travels over the wire.
+```tsx
+import { OrderConfirmation } from './emails/order-confirmation'
+const { data } = await client.templates.create({
+  name: 'Order confirmation',
+  subject: 'Your order {{order_id}} is confirmed',
+  react: <OrderConfirmation />,
+})
+```
+Use `{{variable}}` placeholders anywhere in your React component; they pass through to the rendered HTML and are substituted at send time when you provide `variables`. If you'd rather render yourself, pass `html` instead.
+### Send using a template
+```ts
+await client.emails.send({
+  from: 'you@yourdomain.com',
+  to: 'user@example.com',
+  templateId: data!.id,
+  variables: {
+    first_name: 'Jane',
+    order_id: 'ORD-1234',
+  },
+})
+```
+### List, get, update, delete
+```ts
+await client.templates.list()
+await client.templates.get(templateId)
+await client.templates.update(templateId, { name: 'New name', subject: 'New subject' })
+await client.templates.delete(templateId)
+```
+---
+## Webhooks
+Receive real-time events when email statuses change.
+### Create a webhook
+```ts
+const { data } = await client.webhooks.create({
+  url: 'https://yourapp.com/webhooks/eusend',
+  events: ['email.sent', 'email.delivered', 'email.bounced', 'email.complained'],
+})
+console.log(data?.secret) // signing secret — only returned once, store it securely
+```
+Pass `'*'` in the events array to subscribe to all events.
+Available events: `email.sent` `email.delivered` `email.bounced` `email.complained` `email.opened` `email.clicked`
+### Verifying webhook signatures
+Every delivery is signed with HMAC-SHA256. Verify the signature before processing:
+```ts
+import { createHmac, timingSafeEqual } from 'crypto'
+function verifyWebhook(req: Request, secret: string): boolean {
+  const webhookId = req.headers.get('x-webhook-id') ?? ''
+  const timestamp = req.headers.get('x-webhook-timestamp') ?? ''
+  const signature = req.headers.get('x-webhook-signature') ?? ''
+  const body = await req.text()
+  const expected = 'v1,' + createHmac('sha256', secret)
+    .update(`${webhookId}.${timestamp}.${body}`)
+    .digest('base64')
+  return timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
+}
+```
+### List, get, update, delete
+```ts
+await client.webhooks.list()
+await client.webhooks.get(webhookId)    // includes recent deliveries
+await client.webhooks.update(webhookId, { events: ['email.bounced'] })
+await client.webhooks.delete(webhookId)
+```
+---
+## Broadcasts
+Send a single email to every contact in an audience.
+### Create a broadcast
+```ts
+const { data } = await client.broadcasts.create({
+  name: 'May newsletter',
+  audienceId: 'aud_...',
+  from: 'Sivert <hello@yourdomain.com>',
+  subject: 'May update',
+  html: '<p>Hi {{first_name}}, here is this month's update...</p>',
+})
+```
+You can also pass a React Email component via `react`, a saved template via `templateId`, or plain HTML. With `react`, the SDK renders to HTML locally before submitting:
+```tsx
+import { MayNewsletter } from './emails/may-newsletter'
+await client.broadcasts.create({
+  name: 'May newsletter',
+  audienceId: 'aud_...',
+  from: 'Sivert <hello@yourdomain.com>',
+  subject: 'May update',
+  react: <MayNewsletter />,
+})
+```
+`{{first_name}}`, `{{last_name}}`, `{{full_name}}`, and `{{email}}` are automatically available per recipient. Custom variables can be defined on the broadcast and are merged with per-recipient data.
+### Send a broadcast
+```ts
+await client.broadcasts.send(broadcastId)
+```
+### Schedule a broadcast
+```ts
+await client.broadcasts.send(broadcastId, {
+  scheduledAt: '2026-06-01T09:00:00.000Z',
+})
+```
+### Cancel a broadcast
+```ts
+await client.broadcasts.cancel(broadcastId)
+```
+### List, get, update, delete
+```ts
+await client.broadcasts.list()
+await client.broadcasts.get(broadcastId)   // includes delivery stats
+await client.broadcasts.update(broadcastId, { subject: 'Updated subject' })
+await client.broadcasts.delete(broadcastId)
+```
+---
+## Error handling
+Every method returns `{ data, error, headers }`. On success `error` is `null`; on failure `data` is `null`.
+```ts
+const { data, error } = await client.emails.send({ ... })
+if (error) {
+  console.error(error.name)       // 'MONTHLY_LIMIT_EXCEEDED'
+  console.error(error.message)    // 'Monthly send limit exceeded'
+  console.error(error.statusCode) // 429
+} else {
+  console.log(data.id)
+}
+```
+#### Error codes
+| Code | Status | Description |
+|------|--------|-------------|
+| `UNAUTHORIZED` | 401 | Invalid or missing API key |
+| `FORBIDDEN` | 403 | Action not allowed on your plan |
+| `NOT_FOUND` | 404 | Resource not found |
+| `VALIDATION_ERROR` | 400 | Invalid request body |
+| `CONFLICT` | 409 | Resource already exists |
+| `RATE_LIMITED` | 429 | Too many requests |
+| `MONTHLY_LIMIT_EXCEEDED` | 429 | Monthly send quota reached |
+| `DAILY_LIMIT_EXCEEDED` | 429 | Daily send quota reached (free plan) |
+| `PLAN_LIMIT_EXCEEDED` | 403 | Feature not available on your plan |
+| `DOMAIN_NOT_VERIFIED` | 403 | The sender domain is not verified for your organisation |
+| `ALL_SUPPRESSED` | 422 | All recipients are on the suppression list |
+| `INTERNAL_ERROR` | 500 | Server error |
+| `application_error` | `null` | Network failure — request never reached the server |
+---
+## TypeScript
+The SDK is written in TypeScript and ships with full type definitions. All request options, response shapes, and error codes are typed.
+```ts
+import type {
+  SendEmailOptions,
+  Email,
+  EmailStatus,
+  EusendError,
+  EusendResponse,
+} from '@eusend_dev/sdk'
+```
+---
+## Requirements
+- Node.js 18 or later (uses the native `fetch` API)
+- An Eusend account and API key — [eusend.dev](https://eusend.dev)