groundmail 0.16.0 → 0.19.0

package/README.md

@@ -25,6 +25,70 @@ const email = await tx.emails.send({
 console.log(email.id, email.status)
 ```
 
+## Testing
+
+Use a test key (`gm_test_…`, create one with `tx.apiKeys.create({ test: true })` or in the
+dashboard) to run sends through validation, templates and webhooks without delivering anything.
+Simulator addresses produce a specific outcome with any key and never leave Groundmail:
+
+```ts
+import { simulatorAddress } from 'groundmail'
+
+await tx.emails.send({
+  from: 'ops@yourdomain.com',
+  to: simulatorAddress('bounce', 'signup-42'), // bounce+signup-42@simulator.groundmail.dev
+  subject: 'Bounce handling test',
+  html: '<p>Simulated.</p>',
+})
+// status `bounced`, then an `email.bounced` webhook with `data.test: true`
+```
+
+Outcomes: `delivered`, `bounce`, `block`, `complaint`, `suppressed`, `delayed`. Details:
+https://docs.groundmail.dev/testing
+
+## Tenants
+
+If you send email for your own customers, create one tenant per customer. Each tenant has its
+own domains, suppression list, stats, pause switch and daily limit, so one customer's bounces
+or complaints never affect the others. Tenants are included on the Scale and Dedicated plans.
+
+```ts
+await tx.tenants.create({ external_id: 'cus_123', name: 'Acme', daily_limit: 5000 })
+await tx.tenants.domains.assign('cus_123', 'mail.acme.com')
+
+await tx.emails.send({
+  from: 'billing@mail.acme.com',
+  to: 'user@example.com',
+  subject: 'Your invoice',
+  html: '<p>Thanks!</p>',
+  tenant: 'cus_123',
+})
+
+const { stats } = await tx.tenants.stats('cus_123', { days: 7 })
+await tx.tenants.pause('cus_123', 'Unpaid invoice')
+await tx.tenants.resume('cus_123')
+```
+
+`tenant` (your external id or the Groundmail id) also works on `emails.list`, `domains.create` and
+`domains.list`, `suppressions`, `apiKeys.create` (a key limited to one tenant) and
+`emails.testWebhook`. Webhook endpoints take `tenants: ['cus_123']` to receive only those
+tenants' email events. Details: https://docs.groundmail.dev/tenants
+
+## DMARC monitoring
+
+Free for every domain. Turn it on, publish the record it returns, and read sources, pass rates
+and whether it's safe to enforce once the daily reports arrive:
+
+```ts
+const { dmarc } = await tx.dmarc.enable('yourdomain.com') // or { apply: 'cloudflare' }
+console.log(dmarc.dns.suggested_record) // your record with our report address in rua=
+
+const report = await tx.dmarc.get('yourdomain.com')
+if (report.dmarc.enabled) console.log(report.dmarc.readiness.label, report.dmarc.sources)
+```
+
+Details: https://docs.groundmail.dev/dmarc
+
 ## Adapters
 
 Optional entry points (install peer deps as needed):
@@ -41,6 +105,8 @@ Optional entry points (install peer deps as needed):
 
 - Quickstart: https://docs.groundmail.dev/quickstart
 - Node / Nodemailer: https://docs.groundmail.dev/frameworks/node
+- Testing (test keys, simulator): https://docs.groundmail.dev/testing
+- DMARC monitoring: https://docs.groundmail.dev/dmarc
 - API reference: https://docs.groundmail.dev/api/emails
 - Product: https://groundmail.dev
 

package/dist/authjs.d.ts

@@ -1,4 +1,4 @@
-import { G as Groundmail } from './client-DXYsWgOT.js';
+import { G as Groundmail } from './client-H0RF4KEK.js';
 
 /** Subset of Auth.js theme used for the default magic-link email. */
 type AuthjsTheme = {

package/dist/authjs.js

@@ -1,7 +1,7 @@
 import {
   DEFAULT_API_BASE_URL,
   Groundmail
-} from "./chunk-JYLRUBEJ.js";
+} from "./chunk-2RKWN4OE.js";
 
 // src/authjs.ts
 function escapeHtml(value) {

package/dist/better-auth.d.ts

@@ -1,4 +1,4 @@
-import { S as SendEmailResult, G as Groundmail } from './client-DXYsWgOT.js';
+import { S as SendEmailResult, G as Groundmail } from './client-H0RF4KEK.js';
 
 type BetterAuthEmailUser = {
     email: string;

package/dist/better-auth.js

@@ -1,7 +1,7 @@
 import {
   DEFAULT_API_BASE_URL,
   Groundmail
-} from "./chunk-JYLRUBEJ.js";
+} from "./chunk-2RKWN4OE.js";
 
 // src/better-auth.ts
 function linkHtml(label, url) {

package/dist/{chunk-JYLRUBEJ.js → chunk-2RKWN4OE.js}

@@ -895,6 +895,32 @@ var AutomationsResource = class {
   }
 };
 
+// src/dmarc.ts
+var DmarcResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  path(domain) {
+    return `/domains/${encodeURIComponent(domain)}/dmarc`;
+  }
+  /** Monitoring status and the last 30 days of reports. `domain` is the domain id or name. */
+  async get(domain) {
+    return this.client.request(this.path(domain), { method: "GET" });
+  }
+  /** Turn monitoring on. Returns the report address and the DMARC record to publish. */
+  async enable(domain, params = {}) {
+    return this.client.request(this.path(domain), { method: "POST", body: JSON.stringify(params) });
+  }
+  /** Turn the weekly digest email on or off. */
+  async update(domain, params) {
+    return this.client.request(this.path(domain), { method: "PATCH", body: JSON.stringify(params) });
+  }
+  /** Stop monitoring. Remove the address from your DMARC record's rua= tag too. */
+  async disable(domain) {
+    return this.client.request(this.path(domain), { method: "DELETE" });
+  }
+};
+
 // src/domains.ts
 var DomainsResource = class {
   constructor(client) {
@@ -906,6 +932,7 @@ var DomainsResource = class {
     if (params.cursor) search.set("cursor", params.cursor);
     const inboundEnabled = params.inbound_enabled ?? params.inboundEnabled;
     if (inboundEnabled !== void 0) search.set("inbound_enabled", String(inboundEnabled));
+    if (params.tenant) search.set("tenant", params.tenant);
     const query = search.toString();
     return this.client.request(`/domains${query ? `?${query}` : ""}`, { method: "GET" });
   }
@@ -918,7 +945,8 @@ var DomainsResource = class {
       method: "POST",
       body: JSON.stringify({
         name: params.name,
-        ...inboundEnabled !== void 0 ? { inbound_enabled: inboundEnabled } : {}
+        ...inboundEnabled !== void 0 ? { inbound_enabled: inboundEnabled } : {},
+        ...params.tenant ? { tenant: params.tenant } : {}
       })
     });
   }
@@ -1008,6 +1036,8 @@ var EmailsResource = class {
     const search = new URLSearchParams();
     if (params.limit != null) search.set("limit", String(params.limit));
     if (params.cursor) search.set("cursor", params.cursor);
+    if (params.test != null) search.set("test", String(params.test));
+    if (params.tenant) search.set("tenant", params.tenant);
     const query = search.toString();
     return this.client.request(`/emails${query ? `?${query}` : ""}`, {
       method: "GET"
@@ -1073,7 +1103,8 @@ var EmailsResource = class {
         ...params.email_id !== void 0 ? { email_id: params.email_id } : {},
         ...params.webhook_id !== void 0 ? { webhook_id: params.webhook_id } : {},
         ...params.sync !== void 0 ? { sync: params.sync } : {},
-        ...params.deliver !== void 0 ? { deliver: params.deliver } : {}
+        ...params.deliver !== void 0 ? { deliver: params.deliver } : {},
+        ...params.tenant !== void 0 ? { tenant: params.tenant } : {}
       })
     });
   }
@@ -1125,6 +1156,7 @@ var EmailsResource = class {
     }
     if (params.unsubscribe !== void 0) payload.unsubscribe = params.unsubscribe;
     if (params.category !== void 0) payload.category = params.category;
+    if (params.tenant !== void 0) payload.tenant = params.tenant;
     return payload;
   }
 };
@@ -1192,7 +1224,11 @@ var KeysResource = class {
       method: "POST",
       body: JSON.stringify({
         ...params.name ? { name: params.name } : {},
-        ...params.scope ? { scope: params.scope } : {}
+        ...params.scope && !params.scopes?.length ? { scope: params.scope } : {},
+        ...params.scopes?.length ? { scopes: params.scopes } : {},
+        ...params.allowedDomains?.length ? { allowed_domains: params.allowedDomains } : {},
+        ...params.test ? { test: true } : {},
+        ...params.tenant ? { tenant: params.tenant } : {}
       })
     });
   }
@@ -1271,6 +1307,7 @@ var SuppressionsResource = class {
     if (params.limit != null) search.set("limit", String(params.limit));
     if (params.cursor) search.set("cursor", params.cursor);
     if (params.email) search.set("email", params.email);
+    if (params.tenant) search.set("tenant", params.tenant);
     const query = search.toString();
     return this.client.request(`/suppressions${query ? `?${query}` : ""}`, { method: "GET" });
   }
@@ -1280,10 +1317,15 @@ var SuppressionsResource = class {
       body: JSON.stringify(params)
     });
   }
-  /** Remove by suppression id or email address. */
-  async remove(idOrEmail) {
-    if (idOrEmail.includes("@")) {
-      return this.client.request(`/suppressions?email=${encodeURIComponent(idOrEmail)}`, {
+  /**
+   * Remove by suppression id or email address. Pass `tenant` to remove an address
+   * from that tenant's own list (by email address).
+   */
+  async remove(idOrEmail, options = {}) {
+    if (idOrEmail.includes("@") || options.tenant) {
+      const search = new URLSearchParams({ email: idOrEmail });
+      if (options.tenant) search.set("tenant", options.tenant);
+      return this.client.request(`/suppressions?${search.toString()}`, {
         method: "DELETE"
       });
     }
@@ -1369,6 +1411,84 @@ var TemplatesResource = class {
   }
 };
 
+// src/tenants.ts
+var TenantsResource = class {
+  constructor(client) {
+    this.client = client;
+    this.domains = new TenantDomainsResource(client);
+  }
+  async list(params = {}) {
+    const search = new URLSearchParams();
+    if (params.limit != null) search.set("limit", String(params.limit));
+    if (params.cursor) search.set("cursor", params.cursor);
+    if (params.status) search.set("status", params.status);
+    const query = search.toString();
+    return this.client.request(`/tenants${query ? `?${query}` : ""}`, { method: "GET" });
+  }
+  async create(params) {
+    return this.client.request("/tenants", {
+      method: "POST",
+      body: JSON.stringify(params)
+    });
+  }
+  async get(tenant) {
+    return this.client.request(`/tenants/${encodeURIComponent(tenant)}`, { method: "GET" });
+  }
+  async update(tenant, params) {
+    return this.client.request(`/tenants/${encodeURIComponent(tenant)}`, {
+      method: "PATCH",
+      body: JSON.stringify(params)
+    });
+  }
+  /** Stop the tenant's new sends until you resume it. */
+  async pause(tenant, reason) {
+    return this.update(tenant, { status: "paused", ...reason ? { reason } : {} });
+  }
+  /**
+   * Let a tenant you paused send again. A tenant Groundmail paused (`pause_source`
+   * `automated` or `admin`) cannot be resumed this way: contact support.
+   */
+  async resume(tenant) {
+    return this.update(tenant, { status: "active" });
+  }
+  /**
+   * Delete a tenant and its suppression list. Its domains go back to the account,
+   * its emails keep their history, and API keys limited to it stop working.
+   */
+  async delete(tenant) {
+    return this.client.request(`/tenants/${encodeURIComponent(tenant)}`, { method: "DELETE" });
+  }
+  /** Email counts and rates over the last `days` (1–90, default 7), plus the tenant's ramp today. */
+  async stats(tenant, params = {}) {
+    const query = params.days != null ? `?days=${encodeURIComponent(String(params.days))}` : "";
+    return this.client.request(`/tenants/${encodeURIComponent(tenant)}/stats${query}`, {
+      method: "GET"
+    });
+  }
+};
+var TenantDomainsResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  async list(tenant) {
+    return this.client.request(`/tenants/${encodeURIComponent(tenant)}/domains`, { method: "GET" });
+  }
+  /** Give an existing domain of the account (name or id) to the tenant. Only that tenant can then send from it. */
+  async assign(tenant, domain) {
+    return this.client.request(`/tenants/${encodeURIComponent(tenant)}/domains`, {
+      method: "POST",
+      body: JSON.stringify({ domain })
+    });
+  }
+  /** Give the tenant's domain (name or id) back to the whole account. The domain itself stays. */
+  async unassign(tenant, domain) {
+    return this.client.request(
+      `/tenants/${encodeURIComponent(tenant)}/domains/${encodeURIComponent(domain)}`,
+      { method: "DELETE" }
+    );
+  }
+};
+
 // src/webhooks/index.ts
 var WebhooksResource = class {
   constructor(client) {
@@ -1425,7 +1545,9 @@ var Groundmail = class {
     this.smtpCredentials = new SmtpCredentialsResource(this);
     this.suppressions = new SuppressionsResource(this);
     this.templates = new TemplatesResource(this);
+    this.tenants = new TenantsResource(this);
     this.migrations = new MigrationsResource(this);
+    this.dmarc = new DmarcResource(this);
   }
   /**
    * Check one address with Groundmail validation before you accept it (for

package/dist/clerk.d.ts

@@ -1,4 +1,4 @@
-import { G as Groundmail, S as SendEmailResult } from './client-DXYsWgOT.js';
+import { G as Groundmail, S as SendEmailResult } from './client-H0RF4KEK.js';
 
 /**
  * Subset of Clerk `email.created` webhook `data` used for delivery.

package/dist/clerk.js

@@ -1,7 +1,7 @@
 import {
   DEFAULT_API_BASE_URL,
   Groundmail
-} from "./chunk-JYLRUBEJ.js";
+} from "./chunk-2RKWN4OE.js";
 
 // src/clerk.ts
 function resolveApiKey(options) {

package/dist/{client-DXYsWgOT.d.ts → client-H0RF4KEK.d.ts}

@@ -1,6 +1,8 @@
 type ApiErrorCode = 'validation_error' | 'unauthorized' | 'forbidden' | 'not_found' | 'conflict' | 'plan_limit'
 /** 429: the send would go over a new account's daily ramp-up limit; see `details.resets_at`. */
- | 'daily_ramp_limit' | 'domain_limit' | 'idempotency_conflict' | 'rate_limited' | 'upstream_error' | 'not_configured' | 'internal_error';
+ | 'daily_ramp_limit'
+/** 403: the request names a tenant, but tenants are not enabled for this account (Scale and Dedicated plans). */
+ | 'tenants_not_enabled' | 'domain_limit' | 'idempotency_conflict' | 'rate_limited' | 'upstream_error' | 'not_configured' | 'internal_error';
 type SendEmailParams = {
     from: string | {
         email: string;
@@ -59,6 +61,12 @@ type SendEmailParams = {
      * is not accepted: Groundmail is for transactional and product email.
      */
     category?: 'transactional' | 'product';
+    /**
+     * Send as one of your tenants (its external id or Groundmail id). The send uses that
+     * tenant's domains, suppression list, pause switch and daily limit. Omit to send from
+     * the account as a whole, or from a tenant's own domain to use that tenant automatically.
+     */
+    tenant?: string;
 };
 /**
  * Why Groundmail validation held a recipient back before sending:
@@ -78,6 +86,8 @@ type SendEmailResult = {
     status: string;
     /** Present when some recipients were held back and the email went to the rest. */
     held_back?: HeldBackRecipient[];
+    /** `true` on a test send (a `gm_test_…` key or only simulator addresses): nothing was delivered. */
+    test?: true;
 };
 /** `details` on `POST /emails` 422 when Groundmail validation held back every `to` recipient. */
 type HeldBackErrorDetails = {
@@ -111,6 +121,7 @@ type BatchSendEmailResult = {
         id?: string;
         status?: string;
         held_back?: HeldBackRecipient[];
+        test?: true;
         error?: {
             message: string;
             code?: string;
@@ -148,6 +159,11 @@ type EmailListItem = {
     bounce_type: BounceType | null;
     /** Recipients Groundmail validation held back before sending, with why. Empty when none were. */
     held_back: HeldBackRecipient[];
+    /**
+     * `true` when the email never reached the mail server: sent with a test key or only to
+     * simulator addresses. Its status and events are simulated.
+     */
+    test: boolean;
     tags: unknown;
     scheduled_at: string | null;
     cancelled_at: string | null;
@@ -159,6 +175,8 @@ type EmailListItem = {
     opened_at: string | null;
     /** First tracked-link click; requires click tracking on the sending domain. */
     clicked_at: string | null;
+    /** The tenant's external id. Present only when the email was sent as a tenant. */
+    tenant?: string | null;
 };
 type ReceivedEmailAttachmentMeta = {
     filename: string;
@@ -207,6 +225,10 @@ type ListReceivedEmailsResult = {
 type ListEmailsParams = {
     limit?: number;
     cursor?: string;
+    /** `true`: only test emails; `false`: only live ones. Omit for both. */
+    test?: boolean;
+    /** Only this tenant's emails (external id or Groundmail id). */
+    tenant?: string;
 };
 type ListEmailsResult = {
     emails: EmailListItem[];
@@ -261,6 +283,14 @@ type ApiKey = {
     id: string;
     name: string;
     scope: ApiKeyScope;
+    /** Fine-grained scopes (`emails:send`, `domains:read`, …). */
+    scopes?: string[];
+    /** Domains the key may send from; empty means any verified domain. */
+    allowed_domains?: string[];
+    /** A test key (`gm_test_…`): its sends are simulated and never delivered. */
+    test?: boolean;
+    /** The tenant this key is limited to (external id). Absent or null for an account-wide key. */
+    tenant?: string | null;
     prefix: string;
     created_at: string;
     last_used_at: string | null;
@@ -277,11 +307,31 @@ type ListApiKeysResult = {
 type CreateApiKeyParams = {
     name?: string;
     scope?: ApiKeyScope;
+    /** Fine-grained scopes, e.g. `['emails:send']`. Takes precedence over `scope`. */
+    scopes?: string[];
+    /** Verified domains the key may send from (needs `emails:send`, not `full`). */
+    allowedDomains?: string[];
+    /**
+     * Create a test key (`gm_test_…`): same scopes and checks as a live key, but sends are
+     * never delivered. They get simulated events and webhooks and count toward nothing.
+     */
+    test?: boolean;
+    /**
+     * Limit the key to one tenant (external id or Groundmail id): it sends only as that
+     * tenant and sees only that tenant's emails, domains and suppressions.
+     */
+    tenant?: string;
 };
 type CreateApiKeyResult = {
     id: string;
     name: string;
     scope: ApiKeyScope;
+    scopes?: string[];
+    allowed_domains?: string[];
+    /** A test key (`gm_test_…`). */
+    test?: boolean;
+    /** The tenant this key is limited to (external id), when it is. */
+    tenant?: string;
     prefix: string;
     token: string;
     created_at: string;
@@ -326,6 +376,10 @@ type EmailWebhookEventPayload = {
         bounce_reason?: string | null;
         /** Set on `email.bounced` and `email.failed` when the email bounced: `hard` or `block`. */
         bounce_type?: BounceType | null;
+        /** `true` on simulated events (test keys, simulator addresses, `POST /emails/test`). Absent on real mail. */
+        test?: true;
+        /** The tenant's external id, when the email was sent as a tenant. */
+        tenant?: string;
     };
 };
 /** `contact.unsubscribed` webhook payload (`scope` distinguishes global vs category opt-out). */
@@ -356,10 +410,14 @@ type SuppressedErrorDetails = {
 };
 /**
  * `details` on a 429 `daily_ramp_limit`: the send would go over a new account's
- * daily ramp-up limit for its stream. Send the rest after `resets_at`.
+ * daily ramp-up limit for its stream, or over a tenant's own daily limit (then
+ * `tenant` is set). Send the rest after `resets_at`.
  */
 type DailyRampLimitErrorDetails = {
-    stream: 'transactional' | 'product';
+    /** Set when a tenant's own daily limit or ramp refused the send: the tenant's external id. */
+    tenant?: string;
+    /** The stream whose limit was reached. Absent when a tenant's fixed `daily_limit` was reached. */
+    stream?: 'transactional' | 'product';
     /** Today's recipient limit for this stream. */
     daily_limit: number;
     /** Recipients already sent today on this stream. */
@@ -367,7 +425,7 @@ type DailyRampLimitErrorDetails = {
     /** Recipients (to + cc + bcc) in the refused send. */
     recipients: number;
     /** Ramp-up stage, 1-based; null with a fixed limit set by support. */
-    ramp_stage: number | null;
+    ramp_stage?: number | null;
     /** The next 00:00 UTC, ISO 8601. */
     resets_at: string;
 };
@@ -381,6 +439,8 @@ type TestEmailWebhookParams = {
     sync?: boolean;
     /** When true (default), enqueue delivery to account webhooks. */
     deliver?: boolean;
+    /** Put this tenant (external id or Groundmail id) on the test payload, to test tenant-filtered webhooks. */
+    tenant?: string;
 };
 type WebhookTestDelivery = {
     endpoint_id: string;
@@ -532,17 +592,23 @@ type WebhookEndpoint = {
     url: string;
     events: string[];
     enabled: boolean;
+    /** Present only when the endpoint receives email events for some tenants only (their external ids). */
+    tenants?: string[];
     created_at: string;
     updated_at: string;
 };
 type CreateWebhookParams = {
     url: string;
     events?: WebhookEventType[];
+    /** Only these tenants' email events (external ids or Groundmail ids). Omit, `[]` or `null` for all. */
+    tenants?: string[] | null;
 };
 type UpdateWebhookParams = {
     url?: string;
     events?: WebhookEventType[];
     enabled?: boolean;
+    /** Only these tenants' email events. `[]` or `null` removes the filter. */
+    tenants?: string[] | null;
 };
 type WebhookEndpointWithSecret = {
     webhook: WebhookEndpoint;
@@ -553,6 +619,8 @@ type Suppression = {
     email: string;
     reason: string | null;
     source: string;
+    /** The tenant's external id, on an entry of a tenant's own list. */
+    tenant?: string;
     created_at: string;
     updated_at: string;
 };
@@ -560,6 +628,8 @@ type ListSuppressionsParams = {
     limit?: number;
     cursor?: string;
     email?: string;
+    /** List this tenant's own suppression list instead of the account's. */
+    tenant?: string;
 };
 type ListSuppressionsResult = {
     data: Suppression[];
@@ -569,6 +639,8 @@ type ListSuppressionsResult = {
 type CreateSuppressionParams = {
     email: string;
     reason?: string;
+    /** Add to this tenant's own list (external id or Groundmail id) instead of the account's. */
+    tenant?: string;
 };
 type TemplateStatus = 'draft' | 'published';
 type TemplateFormat = 'html' | 'blocks';
@@ -724,6 +796,8 @@ type Domain = {
     inbound_enabled: boolean;
     inbound_status: 'disabled' | 'pending' | 'active' | 'error' | string;
     inbound_error: string | null;
+    /** The tenant that owns this domain (external id). Absent for an account-wide domain. */
+    tenant?: string | null;
 };
 type DnsRecord = {
     type: string;
@@ -737,12 +811,16 @@ type CreateDomainParams = {
     name: string;
     inbound_enabled?: boolean;
     inboundEnabled?: boolean;
+    /** Give the new domain to this tenant (external id or Groundmail id). Only that tenant can send from it. */
+    tenant?: string;
 };
 type ListDomainsParams = {
     limit?: number;
     cursor?: string;
     inbound_enabled?: boolean;
     inboundEnabled?: boolean;
+    /** Only this tenant's domains. */
+    tenant?: string;
 };
 type ListDomainsResult = {
     domains: Domain[];
@@ -1008,6 +1086,117 @@ type RunMigrationOptions = {
     /** Waits for `retry_after_seconds` (tests can pass a no-op). */
     sleep?: (ms: number) => Promise<void>;
 };
+type TenantStatus = 'active' | 'paused';
+/** `all` (default) or `transactional_only` (product email is refused for this tenant). */
+type TenantStreamPolicy = 'all' | 'transactional_only';
+/** Who paused a tenant: you over the API, Groundmail support, or Groundmail's automatic checks. */
+type TenantPauseSource = 'api' | 'admin' | 'automated';
+/**
+ * One of your customers, inside your Groundmail account. Each tenant has its own
+ * domains, suppression list, stats, pause switch and daily limit.
+ */
+type Tenant = {
+    id: string;
+    object: 'tenant';
+    /** Your id for this customer. Unique in your account; cannot be changed. */
+    external_id: string;
+    name: string | null;
+    status: TenantStatus;
+    paused_reason: string | null;
+    paused_at: string | null;
+    pause_source: TenantPauseSource | null;
+    /** Completes a bare `from` (`"billing"` → `billing@<domain>`) on sends that name this tenant. */
+    default_from_domain: string | null;
+    stream_policy: TenantStreamPolicy;
+    /** Most recipients per UTC day for this tenant; null for no tenant limit. */
+    daily_limit: number | null;
+    metadata: Record<string, unknown> | null;
+    created_at: string;
+    updated_at: string;
+};
+type ListTenantsParams = {
+    limit?: number;
+    cursor?: string;
+    status?: TenantStatus;
+};
+type ListTenantsResult = {
+    data: Tenant[];
+    has_more: boolean;
+    next_cursor: string | null;
+};
+type CreateTenantParams = {
+    /** Your id for this customer: 1–128 characters of `A-Z a-z 0-9 . _ : @ -`. */
+    external_id: string;
+    name?: string;
+    default_from_domain?: string | null;
+    stream_policy?: TenantStreamPolicy;
+    daily_limit?: number | null;
+    metadata?: Record<string, unknown> | null;
+};
+type UpdateTenantParams = {
+    name?: string | null;
+    default_from_domain?: string | null;
+    stream_policy?: TenantStreamPolicy;
+    daily_limit?: number | null;
+    metadata?: Record<string, unknown> | null;
+    /** `paused` stops this tenant's new sends; `active` resumes them. */
+    status?: TenantStatus;
+    /** Why you paused the tenant (with `status: 'paused'`). */
+    reason?: string;
+};
+type DeleteTenantResult = {
+    ok: boolean;
+    id: string;
+    external_id: string;
+    deleted: true;
+};
+/** A tenant's email counts over the last `days`. Rates are 0–1. */
+type TenantStats = {
+    object: 'tenant_stats';
+    days: number;
+    /** Start of the window, ISO 8601. */
+    from: string;
+    total: number;
+    queued: number;
+    scheduled: number;
+    sent: number;
+    delivered: number;
+    bounced: number;
+    complained: number;
+    failed: number;
+    suppressed: number;
+    opened: number;
+    clicked: number;
+    bounce_rate: number;
+    complaint_rate: number;
+};
+/** A tenant's sending ramp today. `active` is false when no ramp limit applies. */
+type TenantRamp = {
+    object: 'tenant_ramp';
+    active: boolean;
+    /** 1-based stage; null when the ramp does not apply. */
+    stage: number | null;
+    daily_limit: {
+        transactional: number | null;
+        product: number | null;
+    } | null;
+    used_today: {
+        transactional: number;
+        product: number;
+    };
+    completed: boolean;
+    /** The next 00:00 UTC, ISO 8601. */
+    resets_at: string;
+};
+type TenantStatsResult = {
+    /** The tenant's external id. */
+    tenant: string;
+    stats: TenantStats;
+    ramp?: TenantRamp;
+};
+type ListTenantDomainsResult = {
+    data: Domain[];
+};
 
 declare class AutomationsResource {
     private readonly client;
@@ -1033,6 +1222,121 @@ declare class AutomationsResource {
     retryRun(id: string): Promise<AutomationRunResponse>;
 }
 
+/** Status of one sending source in the DMARC reports. `unknown`: an unrecognised server failing DMARC (possible spoofing). */
+type DmarcSourceStatus = 'passing' | 'failing' | 'unknown';
+type DmarcSource = {
+    /** Provider id (`google`, `microsoft`, `groundmail`, `sendgrid`…) or `unknown:<reverse DNS domain>`. */
+    key: string;
+    provider: string;
+    name: string;
+    status: DmarcSourceStatus;
+    messages: number;
+    dmarc_pass: number;
+    /** 0–1. */
+    pass_rate: number;
+    spf_aligned_rate: number;
+    dkim_aligned_rate: number;
+    /** Up to five source IPs, busiest first. */
+    ips: string[];
+    ip_count: number;
+    first_seen: string;
+    last_seen: string;
+};
+type DmarcReadinessVerdict = 'no_data' | 'collecting' | 'fix_sources' | 'ready_quarantine' | 'ready_reject' | 'enforced';
+type DmarcReadiness = {
+    verdict: DmarcReadinessVerdict;
+    label: string;
+    detail: string;
+    days_of_data: number;
+    blocking_sources: string[];
+};
+type DmarcDailyPoint = {
+    date: string;
+    messages: number;
+    dmarc_pass: number;
+    pass_rate: number;
+};
+type DmarcMonitoring = {
+    domain: string;
+    enabled: true;
+    /** `waiting` until the first report arrives. */
+    status: 'waiting' | 'receiving';
+    /** Where receivers send the domain's reports. */
+    report_address: string;
+    /** The `rua=` value: `mailto:<report_address>`. */
+    rua: string;
+    dns: {
+        host: string;
+        record: string | null;
+        rua_present: boolean;
+        policy: string | null;
+        /** The current record with our address added to rua=. Publish this. */
+        suggested_record: string;
+    };
+    digest_enabled: boolean;
+    created_at: string;
+    last_report_at: string | null;
+    window_days: number;
+    summary: {
+        messages: number;
+        dmarc_pass: number;
+        dmarc_fail: number;
+        pass_rate: number;
+        reports: number;
+        reporters: string[];
+    };
+    sources: DmarcSource[];
+    daily: DmarcDailyPoint[];
+    readiness: DmarcReadiness;
+};
+type DmarcMonitoringDisabled = {
+    domain: string;
+    enabled: false;
+    status: 'disabled';
+    dns: {
+        host: string;
+        record: string | null;
+        policy: string | null;
+    };
+};
+type DmarcStatus = DmarcMonitoring | DmarcMonitoringDisabled;
+type EnableDmarcParams = {
+    /** Also write the record through a DNS provider connected under Settings → Integrations. */
+    apply?: 'cloudflare' | 'vercel' | 'godaddy';
+    digest_enabled?: boolean;
+};
+type EnableDmarcResult = {
+    dmarc: DmarcMonitoring;
+    applied: {
+        provider: string;
+        results: unknown;
+    } | null;
+    apply_error?: string;
+};
+/** DMARC monitoring for a sending domain: reports, sources, pass rates and enforcement readiness. */
+declare class DmarcResource {
+    private readonly client;
+    constructor(client: Groundmail);
+    private path;
+    /** Monitoring status and the last 30 days of reports. `domain` is the domain id or name. */
+    get(domain: string): Promise<{
+        dmarc: DmarcStatus;
+    }>;
+    /** Turn monitoring on. Returns the report address and the DMARC record to publish. */
+    enable(domain: string, params?: EnableDmarcParams): Promise<EnableDmarcResult>;
+    /** Turn the weekly digest email on or off. */
+    update(domain: string, params: {
+        digest_enabled: boolean;
+    }): Promise<{
+        dmarc: DmarcStatus;
+    }>;
+    /** Stop monitoring. Remove the address from your DMARC record's rua= tag too. */
+    disable(domain: string): Promise<{
+        dmarc: DmarcStatus;
+        disabled: boolean;
+    }>;
+}
+
 declare class DomainsResource {
     private readonly client;
     constructor(client: Groundmail);
@@ -1157,8 +1461,13 @@ declare class SuppressionsResource {
     create(params: CreateSuppressionParams): Promise<{
         suppression: Suppression;
     }>;
-    /** Remove by suppression id or email address. */
-    remove(idOrEmail: string): Promise<{
+    /**
+     * Remove by suppression id or email address. Pass `tenant` to remove an address
+     * from that tenant's own list (by email address).
+     */
+    remove(idOrEmail: string, options?: {
+        tenant?: string;
+    }): Promise<{
         ok: boolean;
     }>;
 }
@@ -1207,6 +1516,61 @@ declare class TemplatesResource {
     }): Promise<unknown>;
 }
 
+/**
+ * Tenants: one per customer of your platform, each with its own domains,
+ * suppression list, stats, pause switch and daily limit. Every method takes the
+ * tenant's external id (your id for the customer) or its Groundmail id.
+ */
+declare class TenantsResource {
+    private readonly client;
+    /** The domains a tenant owns. */
+    readonly domains: TenantDomainsResource;
+    constructor(client: Groundmail);
+    list(params?: ListTenantsParams): Promise<ListTenantsResult>;
+    create(params: CreateTenantParams): Promise<{
+        tenant: Tenant;
+    }>;
+    get(tenant: string): Promise<{
+        tenant: Tenant;
+    }>;
+    update(tenant: string, params: UpdateTenantParams): Promise<{
+        tenant: Tenant;
+    }>;
+    /** Stop the tenant's new sends until you resume it. */
+    pause(tenant: string, reason?: string): Promise<{
+        tenant: Tenant;
+    }>;
+    /**
+     * Let a tenant you paused send again. A tenant Groundmail paused (`pause_source`
+     * `automated` or `admin`) cannot be resumed this way: contact support.
+     */
+    resume(tenant: string): Promise<{
+        tenant: Tenant;
+    }>;
+    /**
+     * Delete a tenant and its suppression list. Its domains go back to the account,
+     * its emails keep their history, and API keys limited to it stop working.
+     */
+    delete(tenant: string): Promise<DeleteTenantResult>;
+    /** Email counts and rates over the last `days` (1–90, default 7), plus the tenant's ramp today. */
+    stats(tenant: string, params?: {
+        days?: number;
+    }): Promise<TenantStatsResult>;
+}
+declare class TenantDomainsResource {
+    private readonly client;
+    constructor(client: Groundmail);
+    list(tenant: string): Promise<ListTenantDomainsResult>;
+    /** Give an existing domain of the account (name or id) to the tenant. Only that tenant can then send from it. */
+    assign(tenant: string, domain: string): Promise<{
+        domain: Domain;
+    }>;
+    /** Give the tenant's domain (name or id) back to the whole account. The domain itself stays. */
+    unassign(tenant: string, domain: string): Promise<{
+        domain: Domain;
+    }>;
+}
+
 declare class WebhooksResource {
     private readonly client;
     constructor(client: Groundmail);
@@ -1247,8 +1611,12 @@ declare class Groundmail {
     readonly smtpCredentials: SmtpCredentialsResource;
     readonly suppressions: SuppressionsResource;
     readonly templates: TemplatesResource;
+    /** Your platform's customers, each with its own domains, suppressions, stats and limits. */
+    readonly tenants: TenantsResource;
     /** Import from SendGrid, Postmark or Mailgun (Beta). */
     readonly migrations: MigrationsResource;
+    /** DMARC monitoring per domain: report address, sources, pass rates and readiness. */
+    readonly dmarc: DmarcResource;
     constructor(apiKey: string, options?: GroundmailOptions);
     /**
      * Check one address with Groundmail validation before you accept it (for
@@ -1263,4 +1631,4 @@ declare class Groundmail {
     request<T>(path: string, init: RequestInit): Promise<T>;
 }
 
-export { type EmailWebhookEventPayload as $, type ApiErrorBody as A, type BatchSendEmailResult as B, type CategoryUnsubscribedErrorDetails as C, type DnsRecord as D, type CreateSuppressionParams as E, type CreateTemplateParams as F, Groundmail as G, type CreateWebhookParams as H, DEFAULT_API_BASE_URL as I, type DailyRampLimitErrorDetails as J, type DeliverabilityBucket as K, type DeliverabilityDomainInsight as L, type DeliverabilityInsightsResult as M, type DeliverabilityMailServerRelay as N, type DeliverabilityWindow as O, type DnsProviderName as P, type Domain as Q, type DomainBimiAnalysis as R, type SendEmailResult as S, type DomainDetailResult as T, type DomainDmarcAnalysis as U, type DomainDnsAnalysis as V, type DomainStatus as W, type DomainTlsMode as X, type DomainTrackingDns as Y, type DomainTrackingStatus as Z, type EmailListItem as _, type ApiErrorCode as a, type WebhookEndpoint as a$, type EmailWebhookEventType as a0, type EnrollmentSkip as a1, type EventRecord as a2, type GroundmailOptions as a3, type HeldBackErrorDetails as a4, type HeldBackReason as a5, type HeldBackRecipient as a6, type ListApiKeysParams as a7, type ListApiKeysResult as a8, type ListAutomationRunsParams as a9, type ReceivedEmailAttachmentMeta as aA, type RemoteApplyDnsCredentials as aB, type RunMigrationOptions as aC, type SendEmailParams as aD, type SuppressedErrorDetails as aE, type Suppression as aF, type Template as aG, type TemplateFormat as aH, type TemplateLintWarning as aI, type TemplateStarter as aJ, type TemplateStatus as aK, type TemplateVersion as aL, type TestEmailWebhookParams as aM, type TestEmailWebhookResult as aN, type TriggerEventParams as aO, type TriggerEventResult as aP, type TwilioIntegrationResponse as aQ, type TwilioIntegrationStatus as aR, type UpdateAutomationParams as aS, type UpdateDomainParams as aT, type UpdateEmailParams as aU, type UpdateTemplateParams as aV, type UpdateWebhookParams as aW, type ValidateEmailResult as aX, type ValidationReason as aY, type ValidationVerdict as aZ, type VerifyDomainResult as a_, type ListAutomationRunsResult as aa, type ListAutomationsResult as ab, type ListDomainsParams as ac, type ListDomainsResult as ad, type ListEmailsParams as ae, type ListEmailsResult as af, type ListReceivedEmailsParams as ag, type ListReceivedEmailsResult as ah, type ListSuppressionsParams as ai, type ListSuppressionsResult as aj, type ListTemplatesParams as ak, type ListTemplatesResult as al, type MailServerSigningStatus as am, type Migration as an, type MigrationDnsChange as ao, type MigrationDnsPlan as ap, type MigrationDomainItem as aq, type MigrationItemStatus as ar, type MigrationProvider as as, type MigrationResource as at, type MigrationSummary as au, type MigrationTemplateItem as av, type MigrationTotals as aw, type MigrationWebhookItem as ax, type ReceivedEmail as ay, type ReceivedEmailAttachment as az, type ApiKey as b, type WebhookEndpointWithSecret as b0, type WebhookEventType as b1, mergeMigrations as b2, type ApiKeyScope as c, type ApplyDnsParams as d, type ApplyDnsRecordResult as e, type ApplyDnsResult as f, type Asset as g, type Automation as h, type AutomationResult as i, type AutomationRun as j, type AutomationRunResponse as k, type AutomationRunStatus as l, type AutomationRunStep as m, type AutomationRunStepStatus as n, type AutomationStatus as o, type AutomationStep as p, type AutomationTrigger as q, type BounceType as r, type ConnectTwilioParams as s, type ContactWebhookEventPayload as t, type CreateApiKeyParams as u, type CreateApiKeyResult as v, type CreateAutomationParams as w, type CreateDomainParams as x, type CreateDomainResult as y, type CreateMigrationParams as z };
+export { type Domain as $, type ApiErrorBody as A, type BatchSendEmailResult as B, type CategoryUnsubscribedErrorDetails as C, type DnsRecord as D, type CreateSuppressionParams as E, type CreateTemplateParams as F, Groundmail as G, type CreateTenantParams as H, type CreateWebhookParams as I, DEFAULT_API_BASE_URL as J, type DailyRampLimitErrorDetails as K, type DeleteTenantResult as L, type DeliverabilityBucket as M, type DeliverabilityDomainInsight as N, type DeliverabilityInsightsResult as O, type DeliverabilityMailServerRelay as P, type DeliverabilityWindow as Q, type DmarcDailyPoint as R, type SendEmailResult as S, type DmarcMonitoring as T, type DmarcMonitoringDisabled as U, type DmarcReadiness as V, type DmarcReadinessVerdict as W, type DmarcSource as X, type DmarcSourceStatus as Y, type DmarcStatus as Z, type DnsProviderName as _, type ApiErrorCode as a, type Tenant as a$, type DomainBimiAnalysis as a0, type DomainDetailResult as a1, type DomainDmarcAnalysis as a2, type DomainDnsAnalysis as a3, type DomainStatus as a4, type DomainTlsMode as a5, type DomainTrackingDns as a6, type DomainTrackingStatus as a7, type EmailListItem as a8, type EmailWebhookEventPayload as a9, type ListTenantsResult as aA, type MailServerSigningStatus as aB, type Migration as aC, type MigrationDnsChange as aD, type MigrationDnsPlan as aE, type MigrationDomainItem as aF, type MigrationItemStatus as aG, type MigrationProvider as aH, type MigrationResource as aI, type MigrationSummary as aJ, type MigrationTemplateItem as aK, type MigrationTotals as aL, type MigrationWebhookItem as aM, type ReceivedEmail as aN, type ReceivedEmailAttachment as aO, type ReceivedEmailAttachmentMeta as aP, type RemoteApplyDnsCredentials as aQ, type RunMigrationOptions as aR, type SendEmailParams as aS, type SuppressedErrorDetails as aT, type Suppression as aU, type Template as aV, type TemplateFormat as aW, type TemplateLintWarning as aX, type TemplateStarter as aY, type TemplateStatus as aZ, type TemplateVersion as a_, type EmailWebhookEventType as aa, type EnableDmarcParams as ab, type EnableDmarcResult as ac, type EnrollmentSkip as ad, type EventRecord as ae, type GroundmailOptions as af, type HeldBackErrorDetails as ag, type HeldBackReason as ah, type HeldBackRecipient as ai, type ListApiKeysParams as aj, type ListApiKeysResult as ak, type ListAutomationRunsParams as al, type ListAutomationRunsResult as am, type ListAutomationsResult as an, type ListDomainsParams as ao, type ListDomainsResult as ap, type ListEmailsParams as aq, type ListEmailsResult as ar, type ListReceivedEmailsParams as as, type ListReceivedEmailsResult as at, type ListSuppressionsParams as au, type ListSuppressionsResult as av, type ListTemplatesParams as aw, type ListTemplatesResult as ax, type ListTenantDomainsResult as ay, type ListTenantsParams as az, type ApiKey as b, type TenantPauseSource as b0, type TenantRamp as b1, type TenantStats as b2, type TenantStatsResult as b3, type TenantStatus as b4, type TenantStreamPolicy as b5, type TestEmailWebhookParams as b6, type TestEmailWebhookResult as b7, type TriggerEventParams as b8, type TriggerEventResult as b9, type TwilioIntegrationResponse as ba, type TwilioIntegrationStatus as bb, type UpdateAutomationParams as bc, type UpdateDomainParams as bd, type UpdateEmailParams as be, type UpdateTemplateParams as bf, type UpdateTenantParams as bg, type UpdateWebhookParams as bh, type ValidateEmailResult as bi, type ValidationReason as bj, type ValidationVerdict as bk, type VerifyDomainResult as bl, type WebhookEndpoint as bm, type WebhookEndpointWithSecret as bn, type WebhookEventType as bo, mergeMigrations as bp, type ApiKeyScope as c, type ApplyDnsParams as d, type ApplyDnsRecordResult as e, type ApplyDnsResult as f, type Asset as g, type Automation as h, type AutomationResult as i, type AutomationRun as j, type AutomationRunResponse as k, type AutomationRunStatus as l, type AutomationRunStep as m, type AutomationRunStepStatus as n, type AutomationStatus as o, type AutomationStep as p, type AutomationTrigger as q, type BounceType as r, type ConnectTwilioParams as s, type ContactWebhookEventPayload as t, type CreateApiKeyParams as u, type CreateApiKeyResult as v, type CreateAutomationParams as w, type CreateDomainParams as x, type CreateDomainResult as y, type CreateMigrationParams as z };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { A as ApiErrorBody, D as DnsRecord } from './client-DXYsWgOT.js';
-export { a as ApiErrorCode, b as ApiKey, c as ApiKeyScope, d as ApplyDnsParams, e as ApplyDnsRecordResult, f as ApplyDnsResult, g as Asset, h as Automation, i as AutomationResult, j as AutomationRun, k as AutomationRunResponse, l as AutomationRunStatus, m as AutomationRunStep, n as AutomationRunStepStatus, o as AutomationStatus, p as AutomationStep, q as AutomationTrigger, B as BatchSendEmailResult, r as BounceType, C as CategoryUnsubscribedErrorDetails, s as ConnectTwilioParams, t as ContactWebhookEventPayload, u as CreateApiKeyParams, v as CreateApiKeyResult, w as CreateAutomationParams, x as CreateDomainParams, y as CreateDomainResult, z as CreateMigrationParams, E as CreateSuppressionParams, F as CreateTemplateParams, H as CreateWebhookParams, I as DEFAULT_API_BASE_URL, J as DailyRampLimitErrorDetails, K as DeliverabilityBucket, L as DeliverabilityDomainInsight, M as DeliverabilityInsightsResult, N as DeliverabilityMailServerRelay, O as DeliverabilityWindow, P as DnsProviderName, Q as Domain, R as DomainBimiAnalysis, T as DomainDetailResult, U as DomainDmarcAnalysis, V as DomainDnsAnalysis, W as DomainStatus, X as DomainTlsMode, Y as DomainTrackingDns, Z as DomainTrackingStatus, _ as EmailListItem, $ as EmailWebhookEventPayload, a0 as EmailWebhookEventType, a1 as EnrollmentSkip, a2 as EventRecord, G as Groundmail, a3 as GroundmailOptions, a4 as HeldBackErrorDetails, a5 as HeldBackReason, a6 as HeldBackRecipient, a7 as ListApiKeysParams, a8 as ListApiKeysResult, a9 as ListAutomationRunsParams, aa as ListAutomationRunsResult, ab as ListAutomationsResult, ac as ListDomainsParams, ad as ListDomainsResult, ae as ListEmailsParams, af as ListEmailsResult, ag as ListReceivedEmailsParams, ah as ListReceivedEmailsResult, ai as ListSuppressionsParams, aj as ListSuppressionsResult, ak as ListTemplatesParams, al as ListTemplatesResult, am as MailServerSigningStatus, an as Migration, ao as MigrationDnsChange, ap as MigrationDnsPlan, aq as MigrationDomainItem, ar as MigrationItemStatus, as as MigrationProvider, at as MigrationResource, au as MigrationSummary, av as MigrationTemplateItem, aw as MigrationTotals, ax as MigrationWebhookItem, ay as ReceivedEmail, az as ReceivedEmailAttachment, aA as ReceivedEmailAttachmentMeta, aB as RemoteApplyDnsCredentials, aC as RunMigrationOptions, aD as SendEmailParams, S as SendEmailResult, aE as SuppressedErrorDetails, aF as Suppression, aG as Template, aH as TemplateFormat, aI as TemplateLintWarning, aJ as TemplateStarter, aK as TemplateStatus, aL as TemplateVersion, aM as TestEmailWebhookParams, aN as TestEmailWebhookResult, aO as TriggerEventParams, aP as TriggerEventResult, aQ as TwilioIntegrationResponse, aR as TwilioIntegrationStatus, aS as UpdateAutomationParams, aT as UpdateDomainParams, aU as UpdateEmailParams, aV as UpdateTemplateParams, aW as UpdateWebhookParams, aX as ValidateEmailResult, aY as ValidationReason, aZ as ValidationVerdict, a_ as VerifyDomainResult, a$ as WebhookEndpoint, b0 as WebhookEndpointWithSecret, b1 as WebhookEventType, b2 as mergeMigrations } from './client-DXYsWgOT.js';
+import { A as ApiErrorBody, D as DnsRecord } from './client-H0RF4KEK.js';
+export { a as ApiErrorCode, b as ApiKey, c as ApiKeyScope, d as ApplyDnsParams, e as ApplyDnsRecordResult, f as ApplyDnsResult, g as Asset, h as Automation, i as AutomationResult, j as AutomationRun, k as AutomationRunResponse, l as AutomationRunStatus, m as AutomationRunStep, n as AutomationRunStepStatus, o as AutomationStatus, p as AutomationStep, q as AutomationTrigger, B as BatchSendEmailResult, r as BounceType, C as CategoryUnsubscribedErrorDetails, s as ConnectTwilioParams, t as ContactWebhookEventPayload, u as CreateApiKeyParams, v as CreateApiKeyResult, w as CreateAutomationParams, x as CreateDomainParams, y as CreateDomainResult, z as CreateMigrationParams, E as CreateSuppressionParams, F as CreateTemplateParams, H as CreateTenantParams, I as CreateWebhookParams, J as DEFAULT_API_BASE_URL, K as DailyRampLimitErrorDetails, L as DeleteTenantResult, M as DeliverabilityBucket, N as DeliverabilityDomainInsight, O as DeliverabilityInsightsResult, P as DeliverabilityMailServerRelay, Q as DeliverabilityWindow, R as DmarcDailyPoint, T as DmarcMonitoring, U as DmarcMonitoringDisabled, V as DmarcReadiness, W as DmarcReadinessVerdict, X as DmarcSource, Y as DmarcSourceStatus, Z as DmarcStatus, _ as DnsProviderName, $ as Domain, a0 as DomainBimiAnalysis, a1 as DomainDetailResult, a2 as DomainDmarcAnalysis, a3 as DomainDnsAnalysis, a4 as DomainStatus, a5 as DomainTlsMode, a6 as DomainTrackingDns, a7 as DomainTrackingStatus, a8 as EmailListItem, a9 as EmailWebhookEventPayload, aa as EmailWebhookEventType, ab as EnableDmarcParams, ac as EnableDmarcResult, ad as EnrollmentSkip, ae as EventRecord, G as Groundmail, af as GroundmailOptions, ag as HeldBackErrorDetails, ah as HeldBackReason, ai as HeldBackRecipient, aj as ListApiKeysParams, ak as ListApiKeysResult, al as ListAutomationRunsParams, am as ListAutomationRunsResult, an as ListAutomationsResult, ao as ListDomainsParams, ap as ListDomainsResult, aq as ListEmailsParams, ar as ListEmailsResult, as as ListReceivedEmailsParams, at as ListReceivedEmailsResult, au as ListSuppressionsParams, av as ListSuppressionsResult, aw as ListTemplatesParams, ax as ListTemplatesResult, ay as ListTenantDomainsResult, az as ListTenantsParams, aA as ListTenantsResult, aB as MailServerSigningStatus, aC as Migration, aD as MigrationDnsChange, aE as MigrationDnsPlan, aF as MigrationDomainItem, aG as MigrationItemStatus, aH as MigrationProvider, aI as MigrationResource, aJ as MigrationSummary, aK as MigrationTemplateItem, aL as MigrationTotals, aM as MigrationWebhookItem, aN as ReceivedEmail, aO as ReceivedEmailAttachment, aP as ReceivedEmailAttachmentMeta, aQ as RemoteApplyDnsCredentials, aR as RunMigrationOptions, aS as SendEmailParams, S as SendEmailResult, aT as SuppressedErrorDetails, aU as Suppression, aV as Template, aW as TemplateFormat, aX as TemplateLintWarning, aY as TemplateStarter, aZ as TemplateStatus, a_ as TemplateVersion, a$ as Tenant, b0 as TenantPauseSource, b1 as TenantRamp, b2 as TenantStats, b3 as TenantStatsResult, b4 as TenantStatus, b5 as TenantStreamPolicy, b6 as TestEmailWebhookParams, b7 as TestEmailWebhookResult, b8 as TriggerEventParams, b9 as TriggerEventResult, ba as TwilioIntegrationResponse, bb as TwilioIntegrationStatus, bc as UpdateAutomationParams, bd as UpdateDomainParams, be as UpdateEmailParams, bf as UpdateTemplateParams, bg as UpdateTenantParams, bh as UpdateWebhookParams, bi as ValidateEmailResult, bj as ValidationReason, bk as ValidationVerdict, bl as VerifyDomainResult, bm as WebhookEndpoint, bn as WebhookEndpointWithSecret, bo as WebhookEventType, bp as mergeMigrations } from './client-H0RF4KEK.js';
 
 type GroundmailErrorOptions = {
     code?: string;
@@ -43,6 +43,40 @@ declare function buildSignatureHeader(secret: string, payload: string, timestamp
  */
 declare function verifyWebhookSignature(secret: string, payload: string, header: string | null | undefined, toleranceSec?: number): boolean;
 
+/**
+ * Test mode helpers.
+ *
+ * Simulator addresses at `simulator.groundmail.dev` produce one outcome each, with
+ * the same status and webhooks as real mail, and never leave Groundmail. They work
+ * with live and test keys. Plus addressing tells sends apart:
+ *
+ * ```ts
+ * import { simulatorAddress } from 'groundmail'
+ * await groundmail.emails.send({ from, to: simulatorAddress('bounce', 'signup-42'), subject, html })
+ * // → bounce+signup-42@simulator.groundmail.dev: status `bounced`, `email.bounced` webhook
+ * ```
+ *
+ * Docs: https://docs.groundmail.dev/testing
+ */
+declare const SIMULATOR_DOMAIN = "simulator.groundmail.dev";
+declare const SIMULATOR_OUTCOMES: readonly ["delivered", "bounce", "block", "complaint", "suppressed", "delayed"];
+/**
+ * - `delivered`: `email.delivered`
+ * - `bounce`: hard bounce, `email.bounced` with `bounce_type: "hard"`
+ * - `block`: block bounce, `email.bounced` with `bounce_type: "block"`
+ * - `complaint`: `email.delivered`, then `email.complained`
+ * - `suppressed`: refused like a suppressed recipient (422), `email.suppressed`
+ * - `delayed`: `email.delivery_delayed`
+ */
+type SimulatorOutcome = (typeof SIMULATOR_OUTCOMES)[number];
+/** `simulatorAddress('bounce')` → `bounce@simulator.groundmail.dev`; a tag adds `+tag`. */
+declare function simulatorAddress(outcome: SimulatorOutcome, tag?: string): string;
+/** True for any address at the simulator domain. */
+declare function isSimulatorAddress(address: string): boolean;
+/** Test keys start with `gm_test_`. */
+declare const TEST_API_KEY_PREFIX = "gm_test_";
+declare function isTestApiKey(key: string | null | undefined): boolean;
+
 /** Merge `include:host` into an existing SPF record (or create a minimal one). */
 declare function mergeSpfInclude(existing: string | null | undefined, includeHost: string): string;
 
@@ -75,4 +109,4 @@ declare function applyDnsRecords(input: {
     fetchImpl?: typeof fetch;
 }): Promise<ApplyDnsResult>;
 
-export { DnsRecord, GroundmailError, type GroundmailErrorOptions, applyDnsRecords, buildSignatureHeader, mergeSpfInclude, signWebhookPayload, verifyWebhookSignature };
+export { DnsRecord, GroundmailError, type GroundmailErrorOptions, SIMULATOR_DOMAIN, SIMULATOR_OUTCOMES, type SimulatorOutcome, TEST_API_KEY_PREFIX, applyDnsRecords, buildSignatureHeader, isSimulatorAddress, isTestApiKey, mergeSpfInclude, signWebhookPayload, simulatorAddress, verifyWebhookSignature };

package/dist/index.js

@@ -8,15 +8,41 @@ import {
   mergeSpfInclude,
   signWebhookPayload,
   verifyWebhookSignature
-} from "./chunk-JYLRUBEJ.js";
+} from "./chunk-2RKWN4OE.js";
+
+// src/simulator.ts
+var SIMULATOR_DOMAIN = "simulator.groundmail.dev";
+var SIMULATOR_OUTCOMES = ["delivered", "bounce", "block", "complaint", "suppressed", "delayed"];
+function simulatorAddress(outcome, tag) {
+  if (!SIMULATOR_OUTCOMES.includes(outcome)) {
+    throw new Error(`Unknown simulator outcome: ${outcome}`);
+  }
+  const cleanTag = tag?.trim().replace(/[^A-Za-z0-9._-]+/g, "-");
+  return `${outcome}${cleanTag ? `+${cleanTag}` : ""}@${SIMULATOR_DOMAIN}`;
+}
+function isSimulatorAddress(address) {
+  const match = address.match(/<([^>]+)>/);
+  const bare = (match ? match[1] : address).trim().toLowerCase();
+  return bare.endsWith(`@${SIMULATOR_DOMAIN}`);
+}
+var TEST_API_KEY_PREFIX = "gm_test_";
+function isTestApiKey(key) {
+  return Boolean(key?.startsWith(TEST_API_KEY_PREFIX));
+}
 export {
   DEFAULT_API_BASE_URL,
   Groundmail,
   GroundmailError,
+  SIMULATOR_DOMAIN,
+  SIMULATOR_OUTCOMES,
+  TEST_API_KEY_PREFIX,
   applyDnsRecords,
   buildSignatureHeader,
+  isSimulatorAddress,
+  isTestApiKey,
   mergeMigrations,
   mergeSpfInclude,
   signWebhookPayload,
+  simulatorAddress,
   verifyWebhookSignature
 };

package/dist/payload.d.ts

@@ -1,4 +1,4 @@
-import { G as Groundmail } from './client-DXYsWgOT.js';
+import { G as Groundmail } from './client-H0RF4KEK.js';
 
 /**
  * Minimal Payload `SendEmailOptions` / address shapes used by this adapter.

package/dist/payload.js

@@ -1,7 +1,7 @@
 import {
   DEFAULT_API_BASE_URL,
   Groundmail
-} from "./chunk-JYLRUBEJ.js";
+} from "./chunk-2RKWN4OE.js";
 
 // src/payload.ts
 function resolveApiKey(args) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "groundmail",
-  "version": "0.16.0",
+  "version": "0.19.0",
   "description": "Groundmail transactional email API client",
   "license": "MIT",
   "type": "module",
@@ -89,7 +89,7 @@
     "prepublishOnly": "npm run build && npm run build:nodemailer-bridge"
   },
   "dependencies": {
-    "groundmail-nodemailer": "0.15.2"
+    "groundmail-nodemailer": "0.15.5"
   },
   "devDependencies": {
     "@types/nodemailer": "^8.0.1",