### Installation and Initialization

Source: https://context7.com/kalle-works/euromail-typescript/llms.txt

Install the SDK via npm and initialize the client with your API key or by setting the EUROMAIL_API_KEY environment variable. You can also configure options like timeout, retries, and base URL.

```APIDOC
## Installation and initialization

Install from npm and construct a client with your API key (or set `EUROMAIL_API_KEY` in the environment).

```typescript
import { EuroMail } from "@euromail/sdk";

// Minimal — reads EUROMAIL_API_KEY from process.env
const client = new EuroMail({});

// Explicit key + custom options
const client = new EuroMail({
  apiKey: "em_live_your_api_key_here",
  timeout: 30_000,        // ms, default 30 000
  maxRetries: 2,          // automatic retries for 429/5xx and network errors
  retryBaseDelayMs: 200,  // base for exponential back-off
  baseUrl: "https://api.euromail.dev", // override for testing
});
```
```

--------------------------------

### Install EuroMail SDK

Source: https://github.com/kalle-works/euromail-typescript/blob/main/README.md

Install the SDK using npm. This is the first step before using any of the SDK's functionalities.

```bash
npm install @euromail/sdk
```

--------------------------------

### Install and Initialize EuroMail SDK

Source: https://context7.com/kalle-works/euromail-typescript/llms.txt

Install the SDK via npm and initialize the client. The client can read the API key from the environment or accept it explicitly, along with custom options for timeouts, retries, and base URL.

```typescript
import { EuroMail } from "@euromail/sdk";

// Minimal — reads EUROMAIL_API_KEY from process.env
const client = new EuroMail({});

// Explicit key + custom options
const client = new EuroMail({
  apiKey: "em_live_your_api_key_here",
  timeout: 30_000,        // ms, default 30 000
  maxRetries: 2,          // automatic retries for 429/5xx and network errors
  retryBaseDelayMs: 200,  // base for exponential back-off
  baseUrl: "https://api.euromail.dev", // override for testing
});
```

--------------------------------

### Get Account

Source: https://github.com/kalle-works/euromail-typescript/blob/main/README.md

Get account info and quota.

```APIDOC
## getAccount

### Description
Get account info and quota.

### Method
`getAccount()`
```

--------------------------------

### Quick Start: Send an Email with EuroMail SDK

Source: https://github.com/kalle-works/euromail-typescript/blob/main/README.md

Initialize the SDK with your API key and send a basic email. Ensure your API key is correctly set for live or test environments.

```typescript
import { EuroMail } from "@euromail/sdk";

const euromail = new EuroMail({
  apiKey: "em_live_your_api_key_here",
});

const result = await euromail.sendEmail({
  from: "sender@yourdomain.com",
  to: "recipient@example.com",
  subject: "Hello from EuroMail",
  html_body: "<h1>Welcome!</h1><p>Your account is ready.</p>",
});

console.log(`Email queued: ${result.id}`);
```

--------------------------------

### Get Template

Source: https://github.com/kalle-works/euromail-typescript/blob/main/README.md

Get template by ID.

```APIDOC
## getTemplate

### Description
Get template by ID.

### Method
`getTemplate(id)`
```

--------------------------------

### Configure Inbound Email Routes

Source: https://github.com/kalle-works/euromail-typescript/blob/main/README.md

Examples for creating, updating, and deleting inbound email routes. Supports prefix matching, catch-all, and webhook integration. Requires a 'domain-uuid'.

```typescript
// Route incoming email to a webhook
const route = await euromail.createInboundRoute({
  domain_id: "domain-uuid",
  pattern: "support@",
  match_type: "prefix",
  priority: 10,
  webhook_url: "https://yourdomain.com/inbound/support",
});
```

```typescript
// Update route
await euromail.updateInboundRoute(route.id, {
  webhook_url: "https://yourdomain.com/inbound/v2",
  is_active: true,
});
```

```typescript
// Catch-all route
await euromail.createInboundRoute({
  domain_id: "domain-uuid",
  pattern: "*",
  match_type: "catch_all",
  priority: 100,
});
```

```typescript
// List and delete
const routes = await euromail.listInboundRoutes();
await euromail.deleteInboundRoute(route.id);
```

--------------------------------

### Get Domain

Source: https://github.com/kalle-works/euromail-typescript/blob/main/README.md

Get domain details and DNS records.

```APIDOC
## getDomain

### Description
Get domain details and DNS records.

### Method
`getDomain(id)`
```

--------------------------------

### Get Webhook

Source: https://github.com/kalle-works/euromail-typescript/blob/main/README.md

Get webhook details.

```APIDOC
## getWebhook

### Description
Get webhook details.

### Method
`getWebhook(id)`
```

--------------------------------

### Get Inbound Route

Source: https://github.com/kalle-works/euromail-typescript/blob/main/README.md

Get route details.

```APIDOC
## getInboundRoute

### Description
Get route details.

### Method
`getInboundRoute(id)`
```

--------------------------------

### Get Email

Source: https://github.com/kalle-works/euromail-typescript/blob/main/README.md

Get email details and status.

```APIDOC
## getEmail

### Description
Get email details and status.

### Method
`getEmail(id)`
```

--------------------------------

### Get Analytics Overview

Source: https://github.com/kalle-works/euromail-typescript/blob/main/README.md

Aggregated delivery stats.

```APIDOC
## getAnalyticsOverview

### Description
Aggregated delivery stats.

### Method
`getAnalyticsOverview(query?)`
```

--------------------------------

### Get Contact List

Source: https://github.com/kalle-works/euromail-typescript/blob/main/README.md

Get list details.

```APIDOC
## getContactList

### Description
Get list details.

### Method
`getContactList(id)`
```

--------------------------------

### Get Mailbox

Source: https://github.com/kalle-works/euromail-typescript/blob/main/README.md

Fetch a single mailbox.

```APIDOC
## getMailbox

### Description
Fetch a single mailbox.

### Method
`getMailbox(id)`
```

--------------------------------

### Get Analytics Timeseries

Source: https://github.com/kalle-works/euromail-typescript/blob/main/README.md

Daily metrics over time.

```APIDOC
## getAnalyticsTimeseries

### Description
Daily metrics over time.

### Method
`getAnalyticsTimeseries(query?)`
```

--------------------------------

### Subscribe to Webhook Events and Verify Signatures

Source: https://context7.com/kalle-works/euromail-typescript/llms.txt

Create, update, and test webhooks for email lifecycle events. Includes an Express.js example for verifying incoming request signatures using a shared secret.

```typescript
import { createHmac } from "node:crypto";

// Create
const webhook = await client.createWebhook({
  url: "https://yourdomain.com/webhooks/euromail",
  events: ["delivered", "bounced", "complained", "email.inbound"],
});
console.log("Webhook secret (store securely!):", webhook.secret);

// Update
await client.updateWebhook(webhook.id, {
  url: "https://yourdomain.com/webhooks/v2",
  events: ["delivered", "bounced", "opened", "clicked"],
  is_active: true,
});

// Send a synthetic test event
const test = await client.testWebhook(webhook.id);
console.log(test.message, JSON.stringify(test.payload));

// Verify incoming request signature (Express example)
function verifySignature(rawBody: Buffer, sigHeader: string, secret: string): boolean {
  // sigHeader format: t=1700000000,v1=abcdef...
  const [tPart, v1Part] = sigHeader.split(",");
  const timestamp = tPart.split("=")[1];
  const received = v1Part.split("=")[1];
  const expected = createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody.toString()}`)
    .digest("hex");
  return expected === received;
}

// List & delete
const all = await client.listWebhooks();
await client.deleteWebhook(webhook.id);
```

--------------------------------

### Create and Manage Contact Lists

Source: https://github.com/kalle-works/euromail-typescript/blob/main/README.md

Demonstrates creating a contact list with double opt-in, adding single and bulk contacts, listing contacts with filters, and removing contacts and lists.

```typescript
const list = await euromail.createContactList({
  name: "Newsletter",
  description: "Monthly product updates",
  double_opt_in: true,
});
```

```typescript
const contact = await euromail.addContact(list.id, {
  email: "user@example.com",
  metadata: { first_name: "Jane", source: "signup" },
});
```

```typescript
const result = await euromail.bulkAddContacts(list.id, {
  contacts: [
    { email: "a@example.com", metadata: { name: "Alice" } },
    { email: "b@example.com", metadata: { name: "Bob" } },
  ],
});
console.log(`Inserted: ${result.inserted} of ${result.total_requested}`);
```

```typescript
const contacts = await euromail.listContacts(list.id, {
  page: 1,
  per_page: 50,
  status: "active",
});
```

```typescript
await euromail.removeContact(list.id, "user@example.com");
await euromail.deleteContactList(list.id);
```

--------------------------------

### Create and Use Agent Mailbox with EuroMail SDK

Source: https://github.com/kalle-works/euromail-typescript/blob/main/README.md

Demonstrates how to create an agent mailbox, then enter a loop to continuously wait for, process, and acknowledge incoming messages. Includes error handling for message acknowledgment.

```typescript
import { EuroMail } from "@euromail/sdk";

const euromail = new EuroMail({ apiKey: process.env.EUROMAIL_API_KEY });

// Create a mailbox
const mailbox = await euromail.createMailbox({ display_name: "Support Agent" });

// Long-poll loop for incoming messages
while (true) {
  const leased = await euromail.waitForNextMessage(mailbox.id, { timeout: 30 });
  if (!leased) continue; // 408 timeout — no message arrived, poll again

  const { data: msg, lease_token } = leased;
  try {
    await handle(msg);
    // Ack when done — message will not be redelivered
    await euromail.ackMessage(mailbox.id, msg.id, lease_token);
  } catch (err) {
    // Nack to return the message to the queue for retry
    await euromail.nackMessage(mailbox.id, msg.id, lease_token);
    throw err;
  }
}
```

--------------------------------

### Get Inbound Email

Source: https://github.com/kalle-works/euromail-typescript/blob/main/README.md

Get inbound email details.

```APIDOC
## getInboundEmail

### Description
Get inbound email details.

### Method
`getInboundEmail(id)`
```

--------------------------------

### Register and Verify Sending Domains

Source: https://context7.com/kalle-works/euromail-typescript/llms.txt

Register a domain, retrieve DNS records for verification, and poll for verification status. Configure and verify a custom tracking domain. List and delete domains.

```typescript
// Register
const domain = await client.addDomain("mail.yourdomain.com");
console.log("Add these DNS records:");
for (const [key, rec] of Object.entries(domain.dns_records)) {
  console.log(`  ${key}: ${rec.type} ${rec.host} → ${rec.value}`);
}

// Poll verification (call repeatedly after DNS propagation)
const result = await client.verifyDomain(domain.id);
if (result.domain.spf_verified && result.domain.dkim_verified && result.domain.dmarc_verified) {
  console.log("Domain fully verified — ready to send!");
} else {
  for (const [check, v] of Object.entries(result.checks)) {
    if (!v.verified) console.warn(`  ${check}: ${v.detail}`);
  }
}

// Configure a custom tracking domain for open/click pixel
const tracking = await client.setTrackingDomain(domain.id, "track.yourdomain.com");
console.log(`Add CNAME: track.yourdomain.com → ${tracking.cname_target}`);
await client.verifyTrackingDomain(domain.id);

// List all domains
const list = await client.listDomains({ page: 1, per_page: 25 });
console.log(list.data.map((d) => `${d.domain} verified=${d.dkim_verified}`));

await client.deleteDomain(domain.id);
```

--------------------------------

### Create Webhook

Source: https://github.com/kalle-works/euromail-typescript/blob/main/README.md

Subscribe to events.

```APIDOC
## createWebhook

### Description
Subscribe to events.

### Method
`createWebhook(params)`
```

--------------------------------

### createWebhook

Source: https://github.com/kalle-works/euromail-typescript/blob/main/README.md

Create a new webhook subscription to receive event notifications.

```APIDOC
## createWebhook

### Description
Create a new webhook subscription to receive event notifications.

### Method Signature
```typescript
async createWebhook(options: CreateWebhookOptions): Promise<Webhook>
```

### Parameters
#### CreateWebhookOptions
- **url** (string) - Required - The URL to send webhook events to.
- **events** (Array<string>) - Required - A list of events to subscribe to (e.g., 'delivered', 'bounced').

### Response
#### Success Response (200)
- **(Webhook)** - Object representing the created webhook subscription.

### Example
```typescript
const webhook = await euromail.createWebhook({
  url: "https://yourdomain.com/webhooks/euromail",
  events: ["delivered", "bounced", "complained", "email.inbound"],
});
```
```

--------------------------------

### EuroMail SDK Initialization

Source: https://github.com/kalle-works/euromail-typescript/blob/main/README.md

Initialize the EuroMail SDK with your API key and optional timeout.

```APIDOC
## EuroMail SDK Initialization

### Description
Initialize the EuroMail SDK with your API key and optional timeout.

### Usage
```typescript
const euromail = new EuroMail({
  apiKey: "em_live_your_api_key_here",
  timeout: 30000, // Optional, defaults to 30000ms
});
```

### Parameters
#### Configuration Object
- **apiKey** (string) - Required - Your EuroMail API key.
- **timeout** (number) - Optional - The request timeout in milliseconds. Defaults to 30000.
```

--------------------------------

### Manage Account, API Keys, Billing, GDPR, Audit Logs, and AI Insights

Source: https://context7.com/kalle-works/euromail-typescript/llms.txt

This snippet demonstrates various account and administrative operations using the Euromail SDK. It covers retrieving account details, managing API keys, accessing billing information, exporting and erasing GDPR data, listing audit logs, generating AI insights, and managing sub-accounts.

```typescript
// ---- Account ----
const account = await client.getAccount();
console.log(`Plan: ${account.plan}, used: ${account.emails_sent_this_month}/${account.monthly_quota}`);

const csvExport = await client.exportAccount(); // GDPR data access — returns CSV string
```

```typescript
// ---- API Keys ----
const key = await client.createApiKey({ name: "ci-sender", scopes: ["emails:send"] });
console.log("New key (store now, not shown again):", key.key);
const keys = await client.listApiKeys();
await client.deleteApiKey(key.id);
```

```typescript
// ---- Billing ----
const plans = await client.listPlans();
const sub = await client.getSubscription();
console.log(`Current plan: ${sub.plan} (${sub.subscription_status})`);

const checkout = await client.createCheckout({
  plan: "pro",
  success_url: "https://yourdomain.com/billing/success",
  cancel_url:  "https://yourdomain.com/billing/cancel",
});
// redirect user to checkout.checkout_url

const portal = await client.createBillingPortal({ return_url: "https://yourdomain.com/settings" });
// redirect user to portal.portal_url
```

```typescript
// ---- GDPR ----
const gdprData = await client.gdprExport("user@example.com");
console.log(`Exported ${gdprData.data.emails.length} emails for ${gdprData.data.email_address}`);
await client.gdprErase("user@example.com"); // deletes all PII — irreversible
```

```typescript
// ---- Audit Logs ----
const logs = await client.listAuditLogs({ page: 1, per_page: 50 });
for (const log of logs.data) {
  console.log(`${log.created_at} — ${log.action} on ${log.resource_type} (${log.resource_id})`);
}
```

```typescript
// ---- AI Insights ----
const report = await client.generateInsights();
console.log(report.summary);
for (const finding of report.findings) {
  console.log(`[${finding.severity.toUpperCase()}] ${finding.area}: ${finding.observation}`);
  console.log(`  → ${finding.recommendation}`);
}
```

```typescript
// ---- Sub-Accounts (reseller / white-label) ----
const sub_account = await client.createSubAccount({
  name: "Customer Corp",
  email: "admin@customercorp.com",
  password: "secure-temp-password",
  monthly_quota: 10_000,
});
const subKey = await client.createSubAccountApiKey(sub_account.id, { name: "main" });
console.log("Sub-account key:", subKey.key);
await client.updateSubAccount(sub_account.id, { monthly_quota: 25_000, is_active: true });
const subStats = await client.getSubAccountAnalytics(sub_account.id, { period: "30d" });
await client.deleteSubAccount(sub_account.id);
```

--------------------------------

### Get Analytics Domains

Source: https://github.com/kalle-works/euromail-typescript/blob/main/README.md

Per-domain breakdown.

```APIDOC
## getAnalyticsDomains

### Description
Per-domain breakdown.

### Method
`getAnalyticsDomains(query?)`
```

--------------------------------

### Add Domain

Source: https://github.com/kalle-works/euromail-typescript/blob/main/README.md

Register a sending domain.

```APIDOC
## addDomain

### Description
Register a sending domain.

### Method
`addDomain(domain)`
```

--------------------------------

### Create Contact List

Source: https://github.com/kalle-works/euromail-typescript/blob/main/README.md

Create a contact list.

```APIDOC
## createContactList

### Description
Create a contact list.

### Method
`createContactList(params)`
```

--------------------------------

### Handle API Errors - TypeScript

Source: https://context7.com/kalle-works/euromail-typescript/llms.txt

Catch specific `EuroMailError` subclasses for targeted API error handling. This example demonstrates handling authentication, validation, and rate limit errors.

```typescript
import {
  EuroMail,
  EuroMailError,
  AuthenticationError,
  RateLimitError,
  ValidationError,
} from "@euromail/sdk";

const client = new EuroMail({ apiKey: process.env.EUROMAIL_API_KEY });

try {
  await client.sendEmail({
    from: "noreply@yourdomain.com",
    to: "user@example.com",
    subject: "Hello",
    html_body: "<p>World</p>",
  });
} catch (err) {
  if (err instanceof AuthenticationError) {
    // HTTP 401 — invalid or missing API key
    console.error("Check EUROMAIL_API_KEY:", err.message);
  } else if (err instanceof ValidationError) {
    // HTTP 422 — request failed schema validation
    console.error(`Validation [${err.code}]: ${err.message}`);
    if (err.docsUrl) console.error("Docs:", err.docsUrl);
  } else if (err instanceof RateLimitError) {
    // HTTP 429
    const wait = err.retryAfter ?? 60;
    console.warn(`Rate limited — retry after ${wait}s`);
    await new Promise((r) => setTimeout(r, wait * 1000));
  } else if (err instanceof EuroMailError) {
    // Other 4xx/5xx
    console.error(`[HTTP ${err.status}] ${err.code}: ${err.message}`);
    if (err.requestId) console.error("Request-ID:", err.requestId);
  } else {
    throw err; // network error, timeout, etc.
  }
}
```

--------------------------------

### Configure EuroMail SDK Options

Source: https://github.com/kalle-works/euromail-typescript/blob/main/README.md

Configure the SDK with your API key and optional settings like timeout. The API key is required for authentication.

```typescript
const euromail = new EuroMail({
  apiKey: "em_live_...",     // Required
  timeout: 30000,            // Default: 30000ms
});
```

--------------------------------

### listWebhooks

Source: https://github.com/kalle-works/euromail-typescript/blob/main/README.md

List all configured webhook subscriptions.

```APIDOC
## listWebhooks

### Description
List all configured webhook subscriptions.

### Method Signature
```typescript
async listWebhooks(): Promise<ListWebhooksResult>
```

### Response
#### Success Response (200)
- **(ListWebhooksResult)** - Object containing a list of webhook subscriptions.

### Example
```typescript
const webhooks = await euromail.listWebhooks();
```
```

--------------------------------

### Create, List, Update, and Delete Inbound Email Routes

Source: https://context7.com/kalle-works/euromail-typescript/llms.txt

Configure how incoming emails are routed to webhooks. Supports prefix, exact match, and catch-all patterns. Ensure your domain is verified before setting up routes.

```typescript
const route = await client.createInboundRoute({
  domain_id: "domain-uuid",
  pattern: "support@",
  match_type: "prefix",
  priority: 10,
  webhook_url: "https://yourdomain.com/inbound/support",
});
```

```typescript
await client.createInboundRoute({
  domain_id: "domain-uuid",
  pattern: "billing@yourdomain.com",
  match_type: "exact",
  priority: 5,
  webhook_url: "https://yourdomain.com/inbound/billing",
});
```

```typescript
await client.createInboundRoute({
  domain_id: "domain-uuid",
  pattern: "*",
  match_type: "catch_all",
  priority: 100,
});
```

```typescript
const inbox = await client.listInboundEmails({ page: 1, per_page: 25 });
const msg   = await client.getInboundEmail(inbox.data[0].id);
console.log(`From: ${msg.from_address}, Subject: ${msg.subject}`);
```

```typescript
await client.updateInboundRoute(route.id, { is_active: false });
```

```typescript
await client.deleteInboundRoute(route.id);
```

--------------------------------

### Domain Management

Source: https://context7.com/kalle-works/euromail-typescript/llms.txt

Register a domain, retrieve DNS records for verification, and poll for verification status. Also includes configuring and verifying tracking domains, listing domains, and deleting domains.

```APIDOC
## Domain Management

Register a domain, read back the required DNS records, and trigger verification once records are published.

### Register Domain

```typescript
// Register
const domain = await client.addDomain("mail.yourdomain.com");
console.log("Add these DNS records:");
for (const [key, rec] of Object.entries(domain.dns_records)) {
  console.log(`  ${key}: ${rec.type} ${rec.host} → ${rec.value}`);
}
```

### Verify Domain

Poll verification (call repeatedly after DNS propagation).

```typescript
// Poll verification (call repeatedly after DNS propagation)
const result = await client.verifyDomain(domain.id);
if (result.domain.spf_verified && result.domain.dkim_verified && result.domain.dmarc_verified) {
  console.log("Domain fully verified — ready to send!");
} else {
  for (const [check, v] of Object.entries(result.checks)) {
    if (!v.verified) console.warn(`  ${check}: ${v.detail}`);
  }
}
```

### Configure and Verify Tracking Domain

Configure a custom tracking domain for open/click pixel.

```typescript
// Configure a custom tracking domain for open/click pixel
const tracking = await client.setTrackingDomain(domain.id, "track.yourdomain.com");
console.log(`Add CNAME: track.yourdomain.com → ${tracking.cname_target}`);
await client.verifyTrackingDomain(domain.id);
```

### List Domains

List all registered domains.

```typescript
// List all domains
const list = await client.listDomains({ page: 1, per_page: 25 });
console.log(list.data.map((d) => `${d.domain} verified=${d.dkim_verified}`));
```

### Delete Domain

Delete a registered domain.

```typescript
await client.deleteDomain(domain.id);
```
```

--------------------------------

### Create and Manage Email Templates with EuroMail SDK

Source: https://github.com/kalle-works/euromail-typescript/blob/main/README.md

Create, update, list, and delete email templates using Jinja2-style variables. Templates streamline the process of sending repetitive emails with dynamic content.

```typescript
// Create a template with Jinja2-style variables
const template = await euromail.createTemplate({
  alias: "welcome-email",
  name: "Welcome Email",
  subject: "Welcome, {{ name }}!",
  html_body: "<h1>Hello {{ name }}</h1><p>Welcome to {{ company }}.</p>",
  text_body: "Hello {{ name }}, welcome to {{ company }}.",
});

// Update a template
await euromail.updateTemplate(template.id, {
  subject: "Welcome to {{ company }}, {{ name }}!",
});

// List and delete
const templates = await euromail.listTemplates({ page: 1, per_page: 25 });
await euromail.deleteTemplate(template.id);
```

--------------------------------

### Manage Contact Lists and Subscribers

Source: https://context7.com/kalle-works/euromail-typescript/llms.txt

Create contact lists with optional double opt-in, add single or bulk contacts with metadata, list contacts with filters, update list settings, and remove contacts.

```typescript
// Create with double opt-in
const list = await client.createContactList({
  name: "Product Updates",
  description: "Monthly product release emails",
  double_opt_in: true,
});

// Single contact
await client.addContact(list.id, {
  email: "jane@example.com",
  metadata: { first_name: "Jane", source: "signup_form", plan: "pro" },
});

// Bulk import (partial success OK)
const bulk = await client.bulkAddContacts(list.id, {
  contacts: [
    { email: "alice@example.com", metadata: { first_name: "Alice" } },
    { email: "bob@example.com",   metadata: { first_name: "Bob" } },
    { email: "invalid-address" }, // will be skipped
  ],
});
console.log(`Inserted ${bulk.inserted} of ${bulk.total_requested}`);

// Paginated list with status filter
const contacts = await client.listContacts(list.id, { page: 1, per_page: 100, status: "active" });

// Update list settings
await client.updateContactList(list.id, { name: "Product Updates v2", double_opt_in: false });

// Remove one contact
await client.removeContact(list.id, "jane@example.com");

await client.deleteContactList(list.id); // irreversible
```

--------------------------------

### Create Template

Source: https://github.com/kalle-works/euromail-typescript/blob/main/README.md

Create an email template.

```APIDOC
## createTemplate

### Description
Create an email template.

### Method
`createTemplate(params)`
```

--------------------------------

### List Webhooks

Source: https://github.com/kalle-works/euromail-typescript/blob/main/README.md

List webhooks with pagination.

```APIDOC
## listWebhooks

### Description
List webhooks with pagination.

### Method
`listWebhooks(params?)`
```

--------------------------------

### List Templates

Source: https://github.com/kalle-works/euromail-typescript/blob/main/README.md

List templates with pagination.

```APIDOC
## listTemplates

### Description
List templates with pagination.

### Method
`listTemplates(params?)`
```

--------------------------------

### Create Mailbox

Source: https://github.com/kalle-works/euromail-typescript/blob/main/README.md

Create a persistent email address for an AI agent.

```APIDOC
## createMailbox

### Description
Create a persistent email address for an AI agent.

### Method
`createMailbox(params)`
```

--------------------------------

### listTemplates

Source: https://github.com/kalle-works/euromail-typescript/blob/main/README.md

List all available email templates with pagination.

```APIDOC
## listTemplates

### Description
List all available email templates with pagination.

### Method Signature
```typescript
async listTemplates(options?: PaginationOptions): Promise<ListTemplatesResult>
```

### Parameters
#### PaginationOptions
- **page** (number) - Optional - The page number for pagination. Defaults to 1.
- **per_page** (number) - Optional - The number of items per page. Defaults to 25.

### Response
#### Success Response (200)
- **(ListTemplatesResult)** - Object containing a list of templates and pagination information.

### Example
```typescript
const templates = await euromail.listTemplates({ page: 1, per_page: 25 });
```
```

--------------------------------

### testWebhook

Source: https://github.com/kalle-works/euromail-typescript/blob/main/README.md

Send a test event to a webhook to verify its configuration.

```APIDOC
## testWebhook

### Description
Send a test event to a webhook to verify its configuration.

### Method Signature
```typescript
async testWebhook(webhookId: string): Promise<TestWebhookResult>
```

### Parameters
#### Path Parameters
- **webhookId** (string) - Required - The unique identifier of the webhook to test.

### Response
#### Success Response (200)
- **(TestWebhookResult)** - Object indicating the result of the test event.

### Example
```typescript
const test = await euromail.testWebhook(webhook.id);
```
```

--------------------------------

### Test Webhook

Source: https://github.com/kalle-works/euromail-typescript/blob/main/README.md

Send a test event.

```APIDOC
## testWebhook

### Description
Send a test event.

### Method
`testWebhook(id)`
```

--------------------------------

### verifyDomain

Source: https://github.com/kalle-works/euromail-typescript/blob/main/README.md

Trigger the verification process for a previously added domain.

```APIDOC
## verifyDomain

### Description
Trigger the verification process for a previously added domain.

### Method Signature
```typescript
async verifyDomain(domainId: string): Promise<DomainVerification>
```

### Parameters
#### Path Parameters
- **domainId** (string) - Required - The unique identifier of the domain to verify.

### Response
#### Success Response (200)
- **fully_verified** (boolean) - Indicates if the domain is fully verified.

### Example
```typescript
const verification = await euromail.verifyDomain(domain.id);
if (verification.fully_verified) {
  console.log("Domain verified!");
}
```
```

--------------------------------

### Billing Management

Source: https://context7.com/kalle-works/euromail-typescript/llms.txt

Retrieve available plans, current subscription details, and initiate checkout for a new subscription. Access the billing portal for managing existing subscriptions.

```APIDOC
## Billing Management

### Description
Retrieve available plans, current subscription details, and initiate checkout for a new subscription. Access the billing portal for managing existing subscriptions.

### Method
`client.listPlans()`

### Endpoint
N/A (SDK method)

### Response
#### Success Response (200)
- Returns a list of available subscription plans.

### Method
`client.getSubscription()`

### Endpoint
N/A (SDK method)

### Response
#### Success Response (200)
- **plan** (string) - The current subscription plan.
- **subscription_status** (string) - The status of the subscription.

### Method
`client.createCheckout(options: { plan: string, success_url: string, cancel_url: string })`

### Endpoint
N/A (SDK method)

### Parameters
#### Request Body
- **plan** (string) - Required - The desired plan to subscribe to.
- **success_url** (string) - Required - The URL to redirect to upon successful checkout.
- **cancel_url** (string) - Required - The URL to redirect to if the checkout is cancelled.

### Response
#### Success Response (200)
- **checkout_url** (string) - The URL for the checkout session.

### Method
`client.createBillingPortal(options: { return_url: string })`

### Endpoint
N/A (SDK method)

### Parameters
#### Request Body
- **return_url** (string) - Required - The URL to redirect to after exiting the billing portal.

### Response
#### Success Response (200)
- **portal_url** (string) - The URL for the customer billing portal.
```

--------------------------------

### List Inbound Routes

Source: https://github.com/kalle-works/euromail-typescript/blob/main/README.md

List routes with pagination.

```APIDOC
## listInboundRoutes

### Description
List routes with pagination.

### Method
`listInboundRoutes(params?)`
```

--------------------------------

### Manage Account Information

Source: https://github.com/kalle-works/euromail-typescript/blob/main/README.md

Retrieve account details like plan and usage, export all account data for GDPR compliance, or permanently delete the account.

```typescript
const account = await euromail.getAccount();
console.log(`Plan: ${account.plan}, Used: ${account.emails_sent_this_month}/${account.monthly_quota}`);
```

```typescript
// Export all account data (GDPR)
const exportData = await euromail.exportAccount();
```

```typescript
// Delete account permanently
await euromail.deleteAccount();
```

--------------------------------

### Verify Domain

Source: https://github.com/kalle-works/euromail-typescript/blob/main/README.md

Trigger DNS verification.

```APIDOC
## verifyDomain

### Description
Trigger DNS verification.

### Method
`verifyDomain(id)`
```

--------------------------------

### Manage Email Templates

Source: https://context7.com/kalle-works/euromail-typescript/llms.txt

Create, update, list, and delete reusable email templates using Jinja2-style placeholders. Templates can be referenced in `sendEmail` via `template_alias`.

```typescript
// Create
const template = await client.createTemplate({
  alias: "password-reset",
  name: "Password Reset",
  subject: "Reset your password, {{ name }}",
  html_body: "<p>Hi {{ name }}, <a href='{{ reset_url }}'>click here</a> to reset your password.</p>",
  text_body: "Hi {{ name }}, visit {{ reset_url }} to reset your password.",
});
```

```typescript
// Update
await client.updateTemplate(template.id, {
  subject: "Action required: reset your {{ company }} password",
  html_body: "<p>Hi {{ name }}, <a href='{{ reset_url }}'>Reset password</a> — expires in 1 hour.</p>",
});
```

```typescript
// List (paginated)
const templates = await client.listTemplates({ page: 1, per_page: 25 });
console.log(templates.data.map((t) => t.alias));
```

```typescript
// Use in sendEmail
await client.sendEmail({
  from: "noreply@yourdomain.com",
  to: "user@example.com",
  template_alias: "password-reset",
  template_data: { name: "Alice", company: "Acme", reset_url: "https://acme.com/reset/xyz" },
});
```

```typescript
// Delete
await client.deleteTemplate(template.id);
```

--------------------------------

### Create and Manage Webhooks with EuroMail SDK

Source: https://github.com/kalle-works/euromail-typescript/blob/main/README.md

Subscribe to email events (e.g., delivered, bounced) by creating webhooks, update existing webhooks, send test events, and list or delete webhooks. Webhooks are essential for real-time event notifications.

```typescript
// Subscribe to delivery events
const webhook = await euromail.createWebhook({
  url: "https://yourdomain.com/webhooks/euromail",
  events: ["delivered", "bounced", "complained", "email.inbound"],
});

// Update webhook
await euromail.updateWebhook(webhook.id, {
  url: "https://yourdomain.com/webhooks/v2",
  events: ["delivered", "bounced"],
  is_active: true,
});

// Send a test event
const test = await euromail.testWebhook(webhook.id);

// List and delete
const webhooks = await euromail.listWebhooks();
await euromail.deleteWebhook(webhook.id);
```

--------------------------------

### Create Inbound Route

Source: https://github.com/kalle-works/euromail-typescript/blob/main/README.md

Create a routing rule.

```APIDOC
## createInboundRoute

### Description
Create a routing rule.

### Method
`createInboundRoute(params)`
```

--------------------------------

### createTemplate

Source: https://github.com/kalle-works/euromail-typescript/blob/main/README.md

Create a new email template with optional subject and body content.

```APIDOC
## createTemplate

### Description
Create a new email template with optional subject and body content.

### Method Signature
```typescript
async createTemplate(options: CreateTemplateOptions): Promise<Template>
```

### Parameters
#### CreateTemplateOptions
- **alias** (string) - Required - A unique alias for the template.
- **name** (string) - Required - The display name of the template.
- **subject** (string) - Optional - The subject line of the template, can include variables.
- **html_body** (string) - Optional - The HTML content of the template, can include variables.
- **text_body** (string) - Optional - The plain text content of the template, can include variables.

### Response
#### Success Response (200)
- **(Template)** - Object representing the created template, including its ID.

### Example
```typescript
const template = await euromail.createTemplate({
  alias: "welcome-email",
  name: "Welcome Email",
  subject: "Welcome, {{ name }}!",
  html_body: "<h1>Hello {{ name }}</h1><p>Welcome to {{ company }}.</p>",
  text_body: "Hello {{ name }}, welcome to {{ company }}.",
});
```
```

--------------------------------

### Send Email Using a Template with EuroMail SDK

Source: https://github.com/kalle-works/euromail-typescript/blob/main/README.md

Send an email using a pre-defined template and provide dynamic data for the template. This is efficient for recurring email types like welcome messages.

```typescript
await euromail.sendEmail({
  from: "noreply@yourdomain.com",
  to: "user@example.com",
  template_alias: "welcome-email",
  template_data: {
    name: "John",
    activation_url: "https://example.com/activate/abc123",
  },
});
```

--------------------------------

### List Domains

Source: https://github.com/kalle-works/euromail-typescript/blob/main/README.md

List domains with pagination.

```APIDOC
## listDomains

### Description
List domains with pagination.

### Method
`listDomains(params?)`
```

--------------------------------

### listDomains

Source: https://github.com/kalle-works/euromail-typescript/blob/main/README.md

List all sending domains associated with your account.

```APIDOC
## listDomains

### Description
List all sending domains associated with your account.

### Method Signature
```typescript
async listDomains(options?: PaginationOptions): Promise<ListDomainsResult>
```

### Parameters
#### PaginationOptions
- **page** (number) - Optional - The page number for pagination. Defaults to 1.
- **per_page** (number) - Optional - The number of items per page. Defaults to 25.

### Response
#### Success Response (200)
- **(ListDomainsResult)** - Object containing a list of domains and pagination information.

### Example
```typescript
const domains = await euromail.listDomains({ page: 1, per_page: 25 });
```
```

--------------------------------

### Create and Consume Agent Mailbox - TypeScript

Source: https://context7.com/kalle-works/euromail-typescript/llms.txt

Provision a persistent inbound email address for an AI agent and consume messages via a lease/ack/nack model. `waitForNextMessage` long-polls and returns `null` on HTTP 408 (no message within the timeout window).

```typescript
import { EuroMail } from "@euromail/sdk";
const client = new EuroMail({ apiKey: process.env.EUROMAIL_API_KEY });

// Create a mailbox
const mailbox = await client.createMailbox({ display_name: "Support Agent" });
console.log(`Mailbox address: ${mailbox.address}`);

// Consume loop (runs forever)
async function consumeMailbox(mailboxId: string) {
  while (true) {
    // Blocks for up to 30s; returns null on timeout (408), LeasedMessage otherwise
    const leased = await client.waitForNextMessage(mailboxId, { timeout: 30 });
    if (!leased) continue; // no message this round — poll again

    const { data: msg, lease_token, lease_expires_at } = leased;
    console.log(`Processing: ${msg.subject} from ${msg.mail_from}`);

    try {
      await processMessage(msg); // your handler
      await client.ackMessage(mailboxId, msg.id, lease_token); // mark done
    } catch (err) {
      console.error("Handler failed, returning to queue:", err);
      await client.nackMessage(mailboxId, msg.id, lease_token); // put back for retry
    }
  }
}

// Other mailbox management
const mailboxes = await client.listMailboxes({ limit: 20, offset: 0 });
const allMessages = await client.listMessages(mailbox.id, { status: "unread", limit: 50 });
await client.deleteMessage(mailbox.id, allMessages[0].id);
await client.deleteMailbox(mailbox.id);

async function processMessage(msg: any) {
  // stub
}
```

--------------------------------

### List Audit Logs

Source: https://github.com/kalle-works/euromail-typescript/blob/main/README.md

List account activity.

```APIDOC
## listAuditLogs

### Description
List account activity.

### Method
`listAuditLogs(params?)`
```

--------------------------------

### Add Contact

Source: https://github.com/kalle-works/euromail-typescript/blob/main/README.md

Add a contact to a list.

```APIDOC
## addContact

### Description
Add a contact to a list.

### Method
`addContact(listId, params)`
```

--------------------------------

### List Audit Logs

Source: https://github.com/kalle-works/euromail-typescript/blob/main/README.md

Retrieve a paginated list of audit logs, useful for tracking actions performed within the account. Logs include creation timestamp, action, and resource type.

```typescript
const logs = await euromail.listAuditLogs({ page: 1, per_page: 50 });
for (const log of logs.data) {
  console.log(`${log.created_at}: ${log.action} on ${log.resource_type}`);
}
```

--------------------------------

### Handle Inbound Emails

Source: https://github.com/kalle-works/euromail-typescript/blob/main/README.md

Shows how to list, retrieve details for, and delete inbound emails. Requires an 'inbound-uuid' for specific operations.

```typescript
// List received emails
const inbound = await euromail.listInboundEmails({ page: 1, per_page: 25 });
```

```typescript
// Get details
const email = await euromail.getInboundEmail("inbound-uuid");
console.log(`From: ${email.from_address}, Subject: ${email.subject}`);
```

```typescript
// Delete
await euromail.deleteInboundEmail("inbound-uuid");
```

--------------------------------

### Export Account

Source: https://github.com/kalle-works/euromail-typescript/blob/main/README.md

Export all account data.

```APIDOC
## exportAccount

### Description
Export all account data.

### Method
`exportAccount()`
```

--------------------------------

### List Mailboxes

Source: https://github.com/kalle-works/euromail-typescript/blob/main/README.md

List mailboxes on the account.

```APIDOC
## listMailboxes

### Description
List mailboxes on the account.

### Method
`listMailboxes(params?)`
```

--------------------------------

### sendEmail

Source: https://context7.com/kalle-works/euromail-typescript/llms.txt

Queues a single transactional email for delivery. Supports direct content, pre-built templates, attachments, and scheduled delivery. An `idempotency_key` can be provided for safe retries.

```APIDOC
## sendEmail — send a single transactional email

Queues one email for delivery. Returns `{ id, status }` where `status` is `"queued"` (HTTP 202). The `from` field must use the apex sending domain. Pass an `idempotency_key` (in params) or `options.idempotencyKey` to enable safe automatic retries on transient failures.

```typescript
import { EuroMail } from "@euromail/sdk";
const client = new EuroMail({ apiKey: process.env.EUROMAIL_API_KEY });

// Direct content
const result = await client.sendEmail({
  from: "noreply@yourdomain.com",
  to: "user@example.com",
  subject: "Order Confirmation #12345",
  html_body: "<h1>Thanks for your order!</h1><p>It ships tomorrow.</p>",
  text_body: "Thanks for your order! It ships tomorrow.",
  reply_to: "support@yourdomain.com",
  cc: ["manager@yourdomain.com"],
  tags: ["order", "confirmation"],
  metadata: { order_id: "12345", customer_tier: "gold" },
  idempotency_key: "order-confirm-12345", // safe to retry
});
console.log(result.id, result.status); // "uuid-..." "queued"

// Send with a pre-built template (use alias, not template_id)
await client.sendEmail({
  from: "noreply@yourdomain.com",
  to: "user@example.com",
  template_alias: "welcome-email",
  template_data: { name: "Jane", activation_url: "https://example.com/activate/abc" },
});

// With a file attachment
const fs = await import("node:fs/promises");
const pdf = await fs.readFile("invoice.pdf");
await client.sendEmail({
  from: "billing@yourdomain.com",
  to: "user@example.com",
  subject: "Your Invoice",
  html_body: "<p>Please find your invoice attached.</p>",
  attachments: [{ filename: "invoice.pdf", content: pdf.toString("base64"), content_type: "application/pdf" }],
});

// Scheduled delivery
await client.sendEmail({
  from: "noreply@yourdomain.com",
  to: "user@example.com",
  subject: "Your Weekly Digest",
  html_body: "<p>Here is this week's digest.</p>",
  // scheduled_at: "2025-09-01T08:00:00Z" — supported by the API
});
```
```

--------------------------------

### Account Management

Source: https://context7.com/kalle-works/euromail-typescript/llms.txt

Retrieve account details including plan information and email usage. Export account data for GDPR compliance.

```APIDOC
## Account Management

### Description
Retrieve account details including plan information and email usage. Export account data for GDPR compliance.

### Method
`client.getAccount()`

### Endpoint
N/A (SDK method)

### Response
#### Success Response (200)
- **plan** (string) - The current subscription plan.
- **emails_sent_this_month** (number) - The number of emails sent this month.
- **monthly_quota** (number) - The monthly email quota.

### Method
`client.exportAccount()`

### Endpoint
N/A (SDK method)

### Description
Initiates an export of account data for GDPR compliance purposes. Returns a CSV string.

### Response
#### Success Response (200)
- **csvExport** (string) - A CSV string containing account data.
```

--------------------------------

### Async Iteration with Paginate Helpers

Source: https://context7.com/kalle-works/euromail-typescript/llms.txt

Provides async-generator helpers for iterating over paginated responses. Use `paginate` for page objects or `paginateItems` for individual items across all pages. Works with any paginated endpoint.

```typescript
// Iterate page objects
for await (const page of client.paginate((p) => client.listEmails({ ...p, status: "delivered" }))) {
  console.log(`Page ${page.pagination.page} / ${page.pagination.total_pages}`);
  for (const email of page.data) processEmail(email);
}
```

```typescript
// Iterate individual items across all pages
for await (const email of client.paginateItems(
  (p) => client.listEmails({ ...p, status: "bounced" }),
  { perPage: 100 }
)) {
  console.log(email.id, email.to_address);
}
```

```typescript
// Works with any paginated endpoint
for await (const contact of client.paginateItems(
  (p) => client.listContacts("list-uuid", { ...p, status: "active" })
)) {
  console.log(contact.email);
}
```

--------------------------------

### Bulk Add Contacts

Source: https://github.com/kalle-works/euromail-typescript/blob/main/README.md

Add multiple contacts.

```APIDOC
## bulkAddContacts

### Description
Add multiple contacts.

### Method
`bulkAddContacts(listId, params)`
```