### Install the YourMail SDK

Source: https://yourmail.dev/docs/guides/nextjs

Install the zero-dependency YourMail client via npm.

```bash
npm install yourmail
```

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

### Install

Source: https://yourmail.dev/docs/sdk

Install the yourmail package via npm.

```APIDOC
## Install

### Description
Install the yourmail package via npm.

### Command
```bash
npm install yourmail
```
```

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

### Usage response example

Source: https://yourmail.dev/docs/api/usage

Example 200 OK response from the /v1/usage endpoint. Shows plan, monthly and daily counts, and domain and webhook allowances.

```json
// 200 OK
{
  "plan": "pro",
  "month": { "count": 12480, "limit": 50000 },
  "day": { "count": 913, "limit": 5000 },
  "domains": { "count": 3, "limit": 10, "suspended": 0 },
  "webhooks": { "count": 2, "limit": 10, "suspended": 0 }
}
```

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

### Install requests

Source: https://yourmail.dev/docs/guides/python

Install the requests library via pip, required for the YourMail client.

```bash
pip install requests
```

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

### Install YourMail and set the API key

Source: https://yourmail.dev/docs/guides/convex

Install the YourMail npm package and set the YOURMAIL_API_KEY environment variable in the Convex deployment environment using the Convex CLI.

```bash
npm install yourmail
```

```bash
npx convex env set YOURMAIL_API_KEY yourmail_...
```

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

### Resend SDK send call (before migration)

Source: https://yourmail.dev/docs/guides/migrate-from-resend

The original Resend SDK call using snake_case options and returning { data, error }. This is the 'Before' example in the migration guide.

```javascript
import { Resend } from "resend";

const resend = new Resend(process.env.RESEND_API_KEY);

const { data, error } = await resend.emails.send({
  from: "Acme <hello@acme.com>",
  to: ["customer@example.com"],
  subject: "Your receipt",
  html: "<p>Thanks for your order.</p>",
  reply_to: "support@acme.com",
  tags: [{ name: "category", value: "receipt" }],
});
```

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

### 200 OK response example

Source: https://yourmail.dev/docs/api/retrieve

Example JSON response for a successful retrieval, showing all fields including status, timestamps, and events array.

```json
// 200 OK
{
  "id": "jn7abc123def456",
  "status": "delivered",
  "from": "hello@mail.acme.com",
  "to": ["alice@example.com"],
  "cc": [],
  "bcc": [],
  "replyTo": null,
  "subject": "Welcome to Acme",
  "html": "<p>Welcome to Acme</p>",
  "text": "Welcome to Acme",
  "tags": [{ "name": "campaign", "value": "welcome" }],
  "sesMessageId": "0102018f1234abcd-...",
  "error": null,
  "createdAt": 1750000000000,
  "scheduledAt": null,
  "sentAt": 1750000001234,
  "openedAt": 1750000090000,
  "clickedAt": null,
  "events": [
    { "type": "send",      "occurredAt": 1750000001234, "meta": null },
    { "type": "delivered", "occurredAt": 1750000004567, "meta": null },
    { "type": "open",      "occurredAt": 1750000090000,
      "meta": { "userAgent": "Mozilla/5.0 ..." } }
  ]
}
```

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

### POST /v1/domains response (201 Created)

Source: https://yourmail.dev/docs/api/domains

Response body for a successful domain creation request. The shape matches what GET returns. The domain starts with status 'pending' and includes DNS records to publish.

```json
{
  "id": "jd7abc...",
  "name": "mail.acme.com",
  "status": "pending",
  "verifiedAt": null,
  "createdAt": 1756800000000,
  "dnsHost": "cloudflare",
  "dnsRecords": [
    {
      "type": "CNAME",
      "name": "abc._domainkey.mail.acme.com",
      "value": "abc.dkim.amazonses.com",
      "found": null,
      "observed": null,
      "targetKeyMissing": null
    }
  ],
  "recommendedRecords": [
    {
      "type": "TXT",
      "name": "_dmarc.mail.acme.com",
      "value": "v=DMARC1; p=none;",
      "found": null,
      "observed": null,
      "targetKeyMissing": null
    }
  ],
  "failureReason": null,
  "dnsCheckedAt": null,
  "dnsRegressedAt": null,
  "suspendedAt": null,
  "trackEngagement": true
}
```

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

### Install YourMail and React Email dependencies

Source: https://yourmail.dev/docs/guides/react-email

Installs the YourMail SDK along with the optional @react-email/render peer dependency and the @react-email/components library. The SDK itself remains zero-dependency; the renderer is only pulled in when using this feature.

```bash
npm install yourmail @react-email/render @react-email/components
```

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

### Batch Send Response Example

Source: https://yourmail.dev/docs/api/batch

Example of a 200 OK response for a batch send, showing one entry per input email in the same order. Each entry is either a success with an id or an error object. The summary field provides a tally of total, succeeded, and failed items.

```json
// 200 OK — one entry per input email (same order)
{
  "data": [
    { "id": "jn7abc123def456" },
    {
      "error": {
        "type": "validation_error",
        "message": "\"to\" contains an invalid email address",
        "docs_url": "https://yourmail.dev/docs/errors#validation_error"
      }
    }
  ],
  // Tally so a status-only client can spot a failure without walking "data".
  "summary": { "total": 2, "succeeded": 1, "failed": 1 }
}
```

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

### API key response examples (201 and 200)

Source: https://yourmail.dev/docs/api/api-keys

Shows the 201 Created response with the plaintext key (returned only once) and the 200 OK list response with live keys only.

```json
// 201 Created — the only time the plaintext is returned
{
  "id": "k1...",          // revoke with DELETE /v1/api-keys/{id}
  "name": "production",
  "scope": "send",
  "last4": "9f3a",
  "key": "yourmail_..."
}

// 200 OK — GET /v1/api-keys (live keys only)
{
  "data": [
    {
      "id": "k1...",
      "name": "production",
      "last4": "9f3a",
      "scope": "send",
      "createdAt": 1756800000000,
      "lastUsedAt": 1756803600000
    }
  ]
}
```

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

### Dispatch SendWelcomeEmail job

Source: https://yourmail.dev/docs/guides/laravel

Shows how to dispatch the SendWelcomeEmail job after a user is created, for example in a registration controller.

```php
// After the user is created, e.g. in your registration controller:
SendWelcomeEmail::dispatch($user);
```

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

### List Emails Response Example

Source: https://yourmail.dev/docs/api/list

Example JSON response from the list emails endpoint. Shows a page of email records with fields like id, to, from, subject, status, tags, and timestamps, plus pagination fields hasMore and nextCursor.

```json
// 200 OK
{
  "data": [
    {
      "id": "jn7abc123def456",
      "to": ["alice@example.com"],
      "from": "hello@mail.acme.com",
      "subject": "Welcome to Acme",
      "status": "delivered",
      "tags": [{ "name": "campaign", "value": "welcome" }],
      "createdAt": 1750000000000,
      "sentAt": 1750000001234,
      "openedAt": 1750000090000,
      "clickedAt": null
    }
  ],
  "hasMore": true,
  "nextCursor": "eyJpZCI6..."
}
```

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

### GET /v1/api-keys

Source: https://yourmail.dev/docs/api/api-keys

Lists all live (active) API keys for the account. The response includes metadata for each key but never the plaintext key.

```APIDOC
## GET /v1/api-keys

### Description
Lists all live (active) API keys for the account. The response includes metadata for each key but never the plaintext key.

### Method
GET

### Endpoint
/v1/api-keys

### Parameters
None

### Response
#### Success Response (200)
- **data** (array) - Array of key objects.
  - **id** (string) - The key ID.
  - **name** (string) - The name of the key.
  - **last4** (string) - The last four characters of the key.
  - **scope** (string) - The scope of the key.
  - **createdAt** (number) - Unix timestamp of creation.
  - **lastUsedAt** (number | null) - Unix timestamp of last use, or null if never used.

#### Response Example
{
  "data": [
    {
      "id": "k1...",
      "name": "production",
      "last4": "9f3a",
      "scope": "send",
      "createdAt": 1756800000000,
      "lastUsedAt": 1756803600000
    }
  ]
}

### Errors
- **401** `authentication_error` - The API key is missing, malformed or revoked.
- **403** `authentication_error` - The key is send-only; listing keys requires a full-access key.
```

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

### POST /v1/domains

Source: https://yourmail.dev/docs/api/domains

Adds a new sending domain and returns its DNS records in the same response. This endpoint is used to automate the initial domain setup.

```APIDOC
## POST /v1/domains

### Description
Adds a new sending domain and returns its DNS records in the same response. This endpoint is used to automate the initial domain setup.

### Method
POST

### Endpoint
https://api.yourmail.dev/v1/domains

### Parameters
#### Request Body
- **name** (string) - Required - The domain name to add, e.g., "mail.acme.com".

### Request Example
{
  "name": "mail.acme.com"
}

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the created domain.
- **name** (string) - The domain name.
- **dnsRecords** (array) - List of DNS records required for verification.
  - **type** (string) - DNS record type (e.g., TXT, CNAME).
  - **name** (string) - DNS record name.
  - **value** (string) - DNS record value.
- **status** (string) - Verification status (e.g., "pending", "verified").

#### Response Example
{
  "id": "domain_123",
  "name": "mail.acme.com",
  "dnsRecords": [
    {
      "type": "TXT",
      "name": "_dmarc.mail.acme.com",
      "value": "v=DMARC1; p=none"
    }
  ],
  "status": "pending"
}
```

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

### Manage suppressions with fetch API

Source: https://yourmail.dev/docs/api/suppressions

Fetch API example for listing, adding, and removing suppressions. Uses YOUR_API_KEY as a bearer token. The remove request URL-encodes the address (alice%40example.com).

```javascript
// List
const res = await fetch("https://api.yourmail.dev/v1/suppressions?limit=50", {
  headers: { Authorization: "Bearer YOUR_API_KEY" },
});

// Add
await fetch("https://api.yourmail.dev/v1/suppressions", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ email: "alice@example.com" }),
});

// Remove
await fetch(
  "https://api.yourmail.dev/v1/suppressions/alice%40example.com",
  { method: "DELETE", headers: { Authorization: "Bearer YOUR_API_KEY" } }
);
```

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

### Manage sending domains with cURL

Source: https://yourmail.dev/docs/api/domains

cURL commands to add a domain, re-check verification, list, get, and delete a domain. Replace YOUR_API_KEY and DOMAIN_ID with your credentials and domain ID.

```bash
# Add
curl -X POST https://api.yourmail.dev/v1/domains \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "mail.acme.com" }'

# Re-check now, instead of waiting for the background poll. Returns the fresh row.
curl -X POST https://api.yourmail.dev/v1/domains/DOMAIN_ID/verify \
  -H "Authorization: Bearer YOUR_API_KEY"

# List / get / remove
curl https://api.yourmail.dev/v1/domains -H "Authorization: Bearer YOUR_API_KEY"
curl https://api.yourmail.dev/v1/domains/DOMAIN_ID -H "Authorization: Bearer YOUR_API_KEY"
curl -X DELETE https://api.yourmail.dev/v1/domains/DOMAIN_ID -H "Authorization: Bearer YOUR_API_KEY"
```

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

### List suppressions response (GET /v1/suppressions)

Source: https://yourmail.dev/docs/api/suppressions

Example response for listing suppressions. The response is cursor-paginated: read `nextCursor` and pass it back as `cursor` until it returns `null`. Suppressions are ordered by address, not newest-first. The `address` is normalised to lower case, `reason` indicates why it was suppressed, and `createdAt` is a Unix millisecond timestamp.

```json
// 200 OK — GET /v1/suppressions
{
  "data": [
    {
      "address": "alice@example.com",
      "reason": "hard_bounce",
      "createdAt": 1750000000000
    }
  ],
  "hasMore": false,
  "nextCursor": null
}
```

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

### Construct YourMail client with API key

Source: https://yourmail.dev/docs/sdk

Import YourMail and create a client instance using the YOURMAIL_API_KEY environment variable. The client defaults to https://api.yourmail.dev; use the optional baseUrl option for other deployments.

```typescript
import { YourMail } from "yourmail";

const yourmail = new YourMail(process.env.YOURMAIL_API_KEY!);
```

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

### Account-side API: usage, domains, keys, webhooks (TypeScript)

Source: https://yourmail.dev/docs/sdk

Covers usage, domain creation, API key creation, webhook creation, and domain verification. Requires a full-access key. Note: usage.month.limit is null on unlimited plans; domain.dnsRecords must be published before verification; hook.secret is only on the create result; domains.verify is safe in a loop and never moves a domain backwards.

```TypeScript
const usage = await yourmail.usage();
// usage.month.limit is null on an unlimited plan — check before subtracting.

const domain = await yourmail.domains.create("mail.acme.com");
domain.dnsRecords; // publish these; domains.get(id).status flips to "verified"

const { key } = await yourmail.apiKeys.create({ name: "ci", scope: "send" });

const hook = await yourmail.webhooks.create({
  url: "https://acme.com/hooks",
  events: ["*"],
});
hook.secret; // on the create result only

// After publishing the DNS records, ask for a re-check instead of waiting for
// the background poll. Safe in a loop: it never moves a domain backwards, and a
// verified one is still re-checked so a repaired DNS record can be confirmed.
const checked = await yourmail.domains.verify(domain.id);
```

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

### Event webhook payloads for email.bounced and email.complained

Source: https://yourmail.dev/docs/webhooks

Both examples use the same JSON payload shape for every webhook POST body. The first shows the base structure with dedupe on the `id` fieldched field. The second documents the additional `recipient` and `reason` fields that appear in `data` for `email.bounced` and `email.complained`, and shows how `recipients` can list multiple affected addresses. The note explains that `reason` is the suppression reason, not the provider's diagnostic, and that `GET /v1/emails/:id` provides the diagnostic on its bounce event.

```json
// Every webhook POST body has this shape:
{
  "id": "evt_01j9abc123def456",          // unique event ID — dedupe on this
  "type": "email.delivered",             // event type
  "created_at": "2026-06-30T12:00:00.000Z",  // ISO 8601 timestamp
  "data": {
    "email_id": "jn7abc123def456",      // the email this event belongs to
    "from": "hello@mail.acme.com",
    "to": ["alice@example.com"],
    "subject": "Your receipt",
    "tags": [{ "name": "category", "value": "receipt" }]
  }
}
```

```json
// email.bounced — data carries the affected recipient and reason:
{
  "id": "evt_01j9xyz789ghi012",
  "type": "email.bounced",
  "created_at": "2026-06-30T12:00:02.000Z",
  "data": {
    "email_id": "jn7abc123def456",
    "from": "hello@mail.acme.com",
    "to": ["alice@example.com"],
    "subject": "Your receipt",
    "tags": [],
    "recipient": "alice@example.com",   // the (first) address that bounced/complained
    "reason": "hard_bounce",             // "hard_bounce" | "complaint" — why it is now suppressed
    "recipients": [                      // every affected address — one event can name several
      { "address": "alice@example.com", "reason": "hard_bounce" }
    ]
  }
}

// email.complained has the same shape — recipient is who filed the complaint.
// `reason` is the suppression reason, not the mailbox provider's diagnostic;
// GET /v1/emails/:id carries that on its bounce event.
```

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

### Construct

Source: https://yourmail.dev/docs/sdk

Create a YourMail client instance with your API key. The client points to https://api.yourmail.dev by default.

```APIDOC
## Construct

### Description
Create a YourMail client instance with your API key. The client points to https://api.yourmail.dev by default.

### Constructor
`new YourMail(apiKey, options?)`

### Parameters
- **apiKey** (string) - Required - Your YourMail API key.
- **options.baseUrl** (string) - Optional - Base URL for the API, defaults to `https://api.yourmail.dev`.

### Example
```typescript
import { YourMail } from "yourmail";

const yourmail = new YourMail(process.env.YOURMAIL_API_KEY!);
```
```

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

### Minimal send script (send.py)

Source: https://yourmail.dev/docs/guides/python

Sends a welcome email using the yourmail library. Requires YOURMAIL_API_KEY environment variable. The from address must be on a verified domain; otherwise use no-reply@yourmail.dev. A successful send returns {"id": "..."}.

```python
# send.py
import os

from yourmail import send_email

email_id = send_email(
    {
        "from": "Acme <hello@mail.acme.com>",
        "to": "customer@example.com",
        "subject": "Welcome aboard",
        "html": "<p>Thanks for signing up.</p>",
        "text": "Thanks for signing up.",
    },
    api_key=os.environ["YOURMAIL_API_KEY"],
)
print("queued", email_id)
```

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

### Bounced message timeline JSON example

Source: https://yourmail.dev/docs/api/retrieve

Example JSON response showing a bounced message timeline with a send event and a bounce event. The bounce event includes bounceType, bounceSubType, and diagnosticCode metadata.

```json
{
  "id": "jn7abc123def456",
  "status": "bounced",
  "error": "Bounced",
  "events": [
    { "type": "send", "occurredAt": 1750000001234, "meta": null },
    {
      "type": "bounce",
      "occurredAt": 1750000003000,
      "meta": {
        "bounceType": "Permanent",
        "bounceSubType": "General",
        "diagnosticCode": "smtp; 550 5.1.1 user unknown"
      }
    }
  ]
}
```

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

### Define WelcomeEmailJob with retry and discard handling

Source: https://yourmail.dev/docs/guides/rails

Active Job that sends a welcome email. Retries on YourmailClient::TransientError, Net::OpenTimeout, and Net::ReadTimeout with polynomially longer waits. Discards on YourmailClient::PermanentError, logging the rejection. Uses idempotency_key derived from the user to avoid duplicate sends on retry, and tags as an array of { name:, value: } hashes.

```ruby
# app/jobs/welcome_email_job.rb
class WelcomeEmailJob < ApplicationJob
  queue_as :default

  # Retry what can succeed later: 5xx, short rate limits, timeouts.
  retry_on YourmailClient::TransientError, wait: :polynomially_longer, attempts: 5
  retry_on Net::OpenTimeout, Net::ReadTimeout, wait: :polynomially_longer, attempts: 5

  # Permanent: the same request will fail the same way. Record it and stop.
  discard_on YourmailClient::PermanentError do |job, error|
    Rails.logger.warn("YourMail rejected #{job.class.name}: #{error.type}: #{error.message}")
  end

  def perform(user)
    YourmailClient.new.send_email(
      from: "Acme <hello@mail.acme.com>",
      to: user.email,
      subject: "Welcome aboard",
      html: "<p>Thanks for signing up.</p>",
      text: "Thanks for signing up.",
      # Derived from the user, not generated per attempt: a retry after a lost
      # response returns the original id instead of sending twice.
      idempotency_key: "welcome:#{user.id}",
      tags: [{ name: "type", value: "welcome" }]
    )
  end
end
```

```ruby
# After the user is created, e.g. in UsersController#create:
WelcomeEmailJob.perform_later(@user)
```

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

### Error response shape with rate_limited example

Source: https://yourmail.dev/docs/errors

Shows the uniform JSON error body every API error returns, including a rate_limited example. On 429 rate_limited responses, the Retry-After header provides the seconds until the rate bucket refills.

```json
// Every error response body has this shape:
{
  "error": {
    "type": "rate_limited",
    "message": "Rate limit exceeded. Retry after 2 seconds.",
    "docs_url": "https://yourmail.dev/docs/errors#rate_limited"
  }
}

// On 429 rate_limited, the response also includes:
// Retry-After: 2   (seconds until the rate bucket refills)
```

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

### Configure YourMail in config/services.php

Source: https://yourmail.dev/docs/guides/laravel

Read the API key from .env using env() in config/services.php. Call env() only from config files; after running php artisan config:cache, calls elsewhere return null.

```php
// config/services.php
return [
    // ...

    'yourmail' => [
        'key' => env('YOURMAIL_API_KEY'),
    ],
];
```

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

### GET /v1/domains

Source: https://yourmail.dev/docs/api/domains

Lists all sending domains associated with the account.

```APIDOC
## GET /v1/domains

### Description
Lists all sending domains associated with the account.

### Method
GET

### Endpoint
https://api.yourmail.dev/v1/domains

### Parameters
(No parameters)

### Request Example
(No request body)

### Response
#### Success Response (200)
- **domains** (array) - List of domain objects.
  - **id** (string) - Domain identifier.
  - **name** (string) - Domain name.
  - **status** (string) - Verification status.

#### Response Example
{
  "domains": [
    {
      "id": "domain_123",
      "name": "mail.acme.com",
      "status": "verified"
    }
  ]
}
```

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

### Minimal send with YourMail (send.mjs)

Source: https://yourmail.dev/docs/guides/node

The shortest working send: creates a YourMail client with YOURMAIL_API_KEY and sends a welcome email with both html and text parts. Run with YOURMAIL_API_KEY=yourmail_… node send.mjs; the client throws if the key is missing, and the from address must be on a verified domain (or use no-reply@yourmail.dev in test mode).

```javascript
import { YourMail } from "yourmail";

const yourmail = new YourMail(process.env.YOURMAIL_API_KEY);

const { id } = await yourmail.send({
  from: "Acme <hello@mail.acme.com>",
  to: "customer@example.com",
  subject: "Welcome aboard",
  html: "<p>Thanks for signing up.</p>",
  text: "Thanks for signing up.",
});

console.log("queued", id);
```

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

### GET /v1/domains/:id

Source: https://yourmail.dev/docs/api/domains

Retrieves details of a specific sending domain by its ID.

```APIDOC
## GET /v1/domains/:id

### Description
Retrieves details of a specific sending domain by its ID.

### Method
GET

### Endpoint
https://api.yourmail.dev/v1/domains/DOMAIN_ID

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

### Request Example
(No request body)

### Response
#### Success Response (200)
- **id** (string) - Domain identifier.
- **name** (string) - Domain name.
- **dnsRecords** (array) - DNS records for the domain.
- **status** (string) - Verification status.

#### Response Example
{
  "id": "domain_123",
  "name": "mail.acme.com",
  "dnsRecords": [],
  "status": "verified"
}
```

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

### Add and verify a sending domain with YourMail SDK

Source: https://yourmail.dev/docs/api/domains

Uses the YourMail SDK to create a domain and get its DNS records, then verify it. Verification is safe to call in a loop: it never moves a domain backwards, and a failed one is terminal and skipped. Poll every 10-30s; a call within ~10s of the last check answers from the stored row without going out to SES.

```TypeScript
import { YourMail } from "yourmail";

const yourmail = new YourMail(process.env.YOURMAIL_API_KEY!);

// Add the domain and get its DNS records in the same call.
const domain = await yourmail.domains.create("mail.acme.com");
for (const r of domain.dnsRecords) {
  console.log(r.type, r.name, r.value);
}

// Verification runs on its own once the records are live, but you do not have to
// wait for the background poll — ask for a re-check the moment you publish them.
// Safe in a loop: it never moves a domain backwards, and a failed one is
// terminal and skipped, so "already done" reads as success rather than an error.
// A verified domain IS still re-checked — that is how you confirm a repaired
// DNS record — but only dnsCheckedAt/dnsRegressedAt move, never status.
// Poll every 10-30s: a call within ~10s of the last check answers from the
// stored row without going out to SES, so a tighter loop buys nothing.
const { status } = await yourmail.domains.verify(domain.id); // "pending" -> "verified"
```

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

### Create the YourMail client once in lib/yourmail.ts

Source: https://yourmail.dev/docs/guides/nextjs

Create a module-scope YourMail instance using the API key from the environment. Import this module only from server code.

```typescript
// lib/yourmail.ts
import { YourMail } from "yourmail";

// Constructed once at module scope. This module must only ever be imported
// from server code — a Server Action, a Route Handler, or a Server Component.
export const yourmail = new YourMail(process.env.YOURMAIL_API_KEY!);
```

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

### Retrieve email with cURL

Source: https://yourmail.dev/docs/api/retrieve

Uses cURL to call the GET /v1/emails/:id endpoint with a Bearer token.

```bash
curl https://api.yourmail.dev/v1/emails/jn7abc123def456 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

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

### GET /v1/domains

Source: https://yourmail.dev/docs/api/domains

Lists all domains for the account. Returns an object with a data array containing domain rows.

```APIDOC
## GET /v1/domains

### Description
Lists all domains for the account. Returns an object with a data array containing domain rows.

### Method
GET

### Endpoint
/v1/domains

### Response
#### Success Response (200 OK)
- **data** (array) - Array of domain objects, each with the same shape as returned by POST /v1/domains.

#### Response Example
{
  "data": [
    {
      "id": "jd7abc...",
      "name": "mail.acme.com",
      "status": "pending",
      "verifiedAt": null,
      "createdAt": 1756800000000,
      "dnsHost": "cloudflare",
      "dnsRecords": [],
      "recommendedRecords": [],
      "failureReason": null,
      "dnsCheckedAt": null,
      "dnsRegressedAt": null,
      "suspendedAt": null,
      "trackEngagement": true
    }
  ]
}
```

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

### yourmail.apiKeys.create({ name, scope })

Source: https://yourmail.dev/docs/sdk

Creates a new API key with a given name and scope. Returns the key value.

```APIDOC
## yourmail.apiKeys.create({ name, scope })

### Description
Creates a new API key with a given name and scope.

### Method
create({ name, scope })

### Parameters
- **name** (string) - Required - The name of the API key.
- **scope** (string) - Required - The scope of the key, e.g., "send".

### Response
- **key** (string) - The API key value.

### Example
```typescript
const { key } = await yourmail.apiKeys.create({ name: "ci", scope: "send" });
```
```

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

### GET /v1/webhooks

Source: https://yourmail.dev/docs/api/webhooks

Retrieves a list of webhook endpoints. The response contains an array of endpoints without the secret field.

```APIDOC
## GET /v1/webhooks

### Description
Retrieves a list of webhook endpoints. The response contains an array of endpoints without the secret field.

### Method
GET

### Endpoint
/v1/webhooks

### Response
#### Success Response (200)
- **data** (array) - List of webhook endpoints, each without the `secret` field.

#### Response Example
{
  "data": [
    {
      "id": "w1...",
      "url": "https://acme.com/hooks/yourmail",
      "events": ["*"],
      "enabled": true,
      "description": null,
      "consecutiveFailures": 0,
      "lastAttemptAt": null,
      "lastResponseStatus": null,
      "lastError": null,
      "suspendedByPlan": false,
      "autoDisabledAt": null
    }
  ]
}
```