mailumi 1.0.0 → 1.2.0

package/README.md

@@ -7,7 +7,8 @@ The official Node.js SDK and CLI for [Mailumi](https://mailumi.com), the email A
 - Every method resolves to `{ data, error }` and never throws for API errors
 - Automatic retries for rate limits and server errors; sends reuse one `Idempotency-Key`, so a retry never sends twice
 - Webhook signature verification built in
-- `npx mailumi send` from the terminal
+- Set up domains, webhooks, templates, campaigns and suppressions from code, not only in the dashboard
+- `npx mailumi send` and every other API call from the terminal
 
 ## Install
 
@@ -117,6 +118,46 @@ const { data: page } = await mailumi.emails.list({ direction: 'inbound' });
 const { data: bytes } = await mailumi.emails.attachment({ id, index: 0 });
 ```
 
+## Set up domains and webhooks
+
+With an API key that has `domains:write` and `webhooks:write`, or Full access, a script, deploy pipeline or AI agent can do the whole setup:
+
+```ts
+const { data: domain } = await mailumi.domains.create({ name: 'mail.yourdomain.com' });
+for (const r of domain.records) console.log(r.type, r.name, r.value, r.required ? '' : '(recommended)');
+
+// After publishing the records at your DNS provider:
+const { data: check } = await mailumi.domains.verify(domain.id);
+check.ready;   // true once the domain can send
+check.message; // what is still missing
+
+const { data: hook } = await mailumi.webhooks.create({
+  name: 'Production',
+  url: 'https://yourapp.com/webhooks/mailumi',
+  events: ['email.delivered', 'email.bounced', 'email.complained'],
+});
+hook.secret; // only returned now: store it as MAILUMI_WEBHOOK_SECRET
+
+await mailumi.webhooks.test(hook.id);
+const { data: deliveries } = await mailumi.webhooks.deliveries(hook.id);
+```
+
+Mailumi also checks new domains every 5 minutes and emails you as soon as one is verified, so there is no need to poll. If you do, wait at least 15 seconds between checks. `domains.update({ id, openTracking, clickTracking })` changes tracking; turning receiving on with `receivingEnabled: true` also needs `mxConsent: true`, because the MX record replaces any mailbox provider the domain uses now.
+
+| Permission | Allows |
+| --- | --- |
+| `email:send` | Send, batch, schedule, reschedule and cancel emails |
+| `email:read` | Read emails, delivery events and attachments |
+| `domains:read` / `domains:write` | Read domains / add, verify, configure and remove them |
+| `webhooks:write` | Create, test, retry and disable webhooks |
+| `templates:write` | Create, change and delete templates |
+| `contacts:write` | Manage audiences and contacts |
+| `campaigns:write` | Create, send and delete campaigns |
+| `suppressions:write` | List and remove suppressed addresses |
+| `full_access` | Everything, including permissions added later |
+
+API keys cannot create or revoke API keys; that stays in the dashboard. A key limited to one domain only sees and manages that domain.
+
 ## Webhooks
 
 Mailumi signs each webhook with the [Standard Webhooks](https://www.standardwebhooks.com/) format. `verifyWebhook` checks the signature and timestamp and returns the parsed event. It needs no API key; the secret defaults to `MAILUMI_WEBHOOK_SECRET`.
@@ -132,17 +173,23 @@ export async function POST(request: Request) {
   if (error) return new Response(error.message, { status: 401 });
 
   if (event.type === 'email.received') {
-    // event.data has from, to, subject, text, html and attachments
+    const { from, reply_to, subject, text, html, message_id, spam, attachments } = event.data;
+    // spam is a boolean; attachments have filename, content_type, size and download_url
+  }
+  if (event.type === 'email.bounced') {
+    const { recipient, bounce } = event.data; // bounce.type is "Permanent" or "Transient"
   }
   return new Response('OK');
 }
 ```
 
+`event.data` is typed by `event.type`: `EmailReceivedData` for `email.received`, and `EmailEventData` for events about email you sent, which is the email plus `recipient` and a detail such as `delivery`, `bounce` or `click`. Every field is described under [Receiving email](https://mailumi.com/docs#receiving) and [Webhooks](https://mailumi.com/docs#webhooks).
+
 `headers` can be a `Headers` object, Node's `req.headers`, or `{ id, timestamp, signature }`. Deliveries can repeat, so store `event.id` and skip ids you have seen. Events: `email.sent`, `email.delivered`, `email.delivery_delayed`, `email.bounced`, `email.complained`, `email.opened`, `email.clicked`, `email.failed`, `email.unsubscribed` and `email.received`.
 
-## Audiences and contacts
+## Audiences, contacts and campaigns
 
-Add contacts from your app for campaigns. Campaigns are written and sent in the dashboard, with an unsubscribe link and one-click unsubscribe in every email. These calls need an API key with the `contacts:write` permission.
+Add contacts from your app for campaigns. Every campaign email gets an unsubscribe link and one-click unsubscribe. Contacts need an API key with the `contacts:write` permission, campaigns `campaigns:write`.
 
 ```ts
 const { data: audience } = await mailumi.audiences.create({ name: 'Newsletter' });
@@ -156,6 +203,25 @@ const { data } = await mailumi.contacts.list({ audienceId: audience.id, search:
 
 Unsubscribing applies to the address in every audience of the workspace, and adding or importing a contact never resubscribes it.
 
+```ts
+const { data: campaign } = await mailumi.campaigns.create({
+  name: 'October update',
+  subject: 'What is new, {{first_name}}',
+  text: 'Hi {{first_name}},\n\nHere is what we shipped this month: https://yourdomain.com/changelog',
+  from: 'Acme <news@yourdomain.com>',
+  audienceId: audience.id,
+});
+
+const { data: draft } = await mailumi.campaigns.get(campaign.id);
+draft.readiness; // { recipients, missing }: fix everything in missing before sending
+
+await mailumi.campaigns.send(campaign.id);
+const { data: sent } = await mailumi.campaigns.get(campaign.id);
+sent.stats; // delivered, bounced, opened, clicked, unsubscribed, ...
+```
+
+Templates for transactional email work the same way: `templates.create({ name, subject, html, variables })` returns an ID to send with `templateId`. `suppressions.list()` shows addresses Mailumi no longer sends to after a bounce or complaint, and `suppressions.remove(address)` allows one again.
+
 ## Errors
 
 ```ts
@@ -173,7 +239,7 @@ if (error) {
 | `unauthorized` | The API key is missing, wrong, revoked or expired. |
 | `forbidden` | The key lacks the permission, or is limited to another domain. |
 | `plan_limit_reached` | The monthly or daily email allowance is used up. |
-| `not_found` | The email, domain, audience or contact does not exist. |
+| `not_found` | The email, domain, webhook, template, audience, contact or campaign does not exist. |
 | `conflict` | The `Idempotency-Key` was used for a different request. |
 | `rate_limited` | Too many requests; retried automatically. |
 | `internal_error`, `service_unavailable` | A temporary problem; retried automatically. |
@@ -202,20 +268,28 @@ npx mailumi emails list
 npx mailumi emails get <id>
 npx mailumi emails cancel <id>
 npx mailumi domains list
+npx mailumi domains add mail.yourdomain.com
+npx mailumi domains verify <domain_id> --wait   # re-checks every 15 seconds until verified
+npx mailumi webhooks create https://yourapp.com/webhooks/mailumi --name Production --events email.delivered,email.bounced
+npx mailumi webhooks test <webhook_id>
+npx mailumi templates create --name Welcome --subject "Welcome, {{first_name}}" --html-file ./welcome.html
 npx mailumi audiences list
 npx mailumi contacts add <audience_id> jane@example.com --first-name Jane
+npx mailumi campaigns create --name "October update" --subject "News" --text-file ./news.txt --from news@yourdomain.com --audience <audience_id>
+npx mailumi campaigns send <campaign_id>
+npx mailumi suppressions list
 ```
 
 Add `--json` for machine-readable output and `--help` for every command and option. The CLI exits with code 1 on errors.
 
 ## AI coding assistants
 
-Mailumi publishes [llms.txt](https://mailumi.com/llms.txt), [llms-full.txt](https://mailumi.com/llms-full.txt), an [OpenAPI 3.1 description](https://mailumi.com/openapi.json) and an [MCP server](https://mailumi.com/docs#mcp), so Cursor, Claude Code, Codex and VS Code can send test emails and check delivery while they build your integration. See [mailumi.com/ai](https://mailumi.com/ai).
+Mailumi publishes [llms.txt](https://mailumi.com/llms.txt), [llms-full.txt](https://mailumi.com/llms-full.txt), an [OpenAPI 3.1 description](https://mailumi.com/openapi.json) and an [MCP server](https://mailumi.com/docs#mcp), so Cursor, Claude Code, Codex and VS Code can send test emails, check delivery and set up domains, webhooks, templates and campaigns while they build your integration. See [mailumi.com/ai](https://mailumi.com/ai).
 
 ## Links
 
 - [Documentation](https://mailumi.com/docs)
-- [Pricing](https://mailumi.com/pricing): the free plan includes 3,000 emails a month
+- [Pricing](https://mailumi.com/pricing): the free plan includes 1,500 emails a month
 - [Support](https://mailumi.com/contact)
 
 ## Versioning

package/dist/cjs/index.d.ts

@@ -2,7 +2,7 @@
  * The official Mailumi SDK. Works anywhere `fetch` exists: Node.js 18+, Bun, Deno and Cloudflare Workers.
  * Every method resolves to `{ data, error }` and never throws for API errors.
  */
-export declare const VERSION = "1.0.0";
+export declare const VERSION = "1.2.0";
 export type ErrorCode = 'invalid_request' | 'unauthorized' | 'plan_limit_reached' | 'forbidden' | 'not_found' | 'method_not_allowed' | 'conflict' | 'payload_too_large' | 'rate_limited' | 'internal_error' | 'service_unavailable' | 'network_error' | 'missing_api_key' | 'invalid_signature' | 'missing_webhook_secret';
 export interface MailumiError {
     name: 'MailumiError';
@@ -116,10 +116,13 @@ export interface DnsRecord {
     value: string;
     priority?: number;
     verified: boolean;
+    /** What DNS returned at this name when it does not match `value`. Only on records that are not verified. */
+    found?: string[];
 }
 export interface Domain {
     id: string;
     name: string;
+    region?: string;
     ownershipVerified?: boolean;
     sendingEnabled?: boolean;
     receivingEnabled?: boolean;
@@ -131,6 +134,125 @@ export interface Domain {
     createdAt?: number;
     records: DnsRecord[];
 }
+export interface DomainVerification {
+    domain: Domain;
+    /** `true` once the domain can send. */
+    ready: boolean;
+    /** What is still missing, or that the domain is ready. */
+    message: string;
+    /** How many required records have a different value at the DNS provider. */
+    wrong?: number;
+}
+export interface DomainSettings {
+    id: string;
+    /** Receive email for the domain and send it to your email.received webhooks. */
+    receivingEnabled?: boolean;
+    /** Must be `true` to turn receiving on: the MX record replaces any mailbox provider the domain uses now. */
+    mxConsent?: boolean;
+    /** Pro and Scale plans. */
+    openTracking?: boolean;
+    /** Pro and Scale plans. */
+    clickTracking?: boolean;
+}
+export type WebhookSubscription = Exclude<WebhookEventType, 'webhook.test'>;
+export interface NewWebhook {
+    name: string;
+    /** A public HTTPS URL on port 443. */
+    url: string;
+    /** Defaults to `['email.received']`. */
+    events?: WebhookSubscription[];
+    /** Only send events for this domain. Leave it out for every domain. */
+    domainId?: string;
+    /** For email.received: only mail to this address before the @, for example "support". */
+    recipient?: string;
+}
+export interface Webhook {
+    object: 'webhook';
+    id: string;
+    name: string;
+    url: string;
+    events: WebhookSubscription[];
+    domain_id: string | null;
+    recipient: string | null;
+    enabled: boolean;
+    created_at: string;
+}
+export interface WebhookDelivery {
+    /** Also the webhook-id header of the request. */
+    id: string;
+    object: 'webhook_delivery';
+    webhook_id: string;
+    event: WebhookEventType;
+    email_id: string | null;
+    status: 'pending' | 'delivered' | 'failed' | 'cancelled';
+    attempts: number;
+    response_code: number | null;
+    last_error: string | null;
+    next_attempt_at: string | null;
+    created_at: string;
+    delivered_at: string | null;
+}
+export interface NewTemplate {
+    name: string;
+    /** Placeholders such as `{{first_name}}` work in the subject and HTML. */
+    subject: string;
+    html: string;
+    /** Default values for placeholders an email does not pass. */
+    variables?: Record<string, string>;
+}
+export interface Template {
+    object: 'template';
+    id: string;
+    name: string;
+    subject: string;
+    html: string;
+    variables: Record<string, string>;
+    created_at: string;
+    updated_at: string;
+}
+export interface NewCampaign {
+    name: string;
+    /** `{{first_name}}`, `{{last_name}}` and `{{email}}` are filled in per contact. */
+    subject: string;
+    /** Plain text. Blank lines start paragraphs and links become clickable. Mailumi adds your postal address and an unsubscribe link. */
+    text: string;
+    /** A sender on a verified domain. Needed before sending. */
+    from?: string;
+    /** Needed before sending. */
+    audienceId?: string | null;
+}
+export type CampaignStats = Record<'total' | 'pending' | 'sent' | 'delivered' | 'bounced' | 'complained' | 'failed' | 'suppressed' | 'opened' | 'clicked' | 'unsubscribed', number>;
+export interface Campaign {
+    object: 'campaign';
+    id: string;
+    name: string;
+    subject: string;
+    text: string;
+    from: string | null;
+    audience_id: string | null;
+    status: 'draft' | 'sending' | 'sent' | 'failed';
+    /** How many contacts it was sent to. */
+    recipients: number;
+    error: string | null;
+    sent_at: string | null;
+    created_at: string;
+    updated_at: string;
+    /** Drafts, from `campaigns.get`: how many contacts it would go to now, and what to fix before sending. */
+    readiness?: {
+        recipients: number;
+        missing: string[];
+    };
+    /** Campaigns that were sent. */
+    stats?: CampaignStats;
+}
+export interface Suppression {
+    object: 'suppression';
+    address: string;
+    reason: 'bounce' | 'complaint' | 'manual';
+    detail: string | null;
+    email_id: string | null;
+    created_at: string;
+}
 export interface Audience {
     object: 'audience';
     id: string;
@@ -189,6 +311,105 @@ export interface WebhookEvent<T = Record<string, any>> {
     created_at: string;
     data: T;
 }
+interface EmailFields {
+    email_id: string;
+    domain_id: string;
+    from: string;
+    to: string[];
+    subject: string;
+    last_event: string;
+    tags: Record<string, string>;
+    created_at: string;
+}
+export interface ReceivedAttachment {
+    id: string;
+    filename: string;
+    content_type: string;
+    /** Set for inline images that the HTML shows with `cid:`. */
+    content_id: string | null;
+    /** Size in bytes. */
+    size: number;
+    /** Download it server-side with `mailumi.emails.attachment({ id: email_id, index })` or a key with email:read. */
+    download_url: string;
+}
+/** `data` of an `email.received` event. */
+export interface EmailReceivedData extends EmailFields {
+    direction: 'inbound';
+    status: 'received';
+    scheduled_at: null;
+    error: null;
+    /** `Name <address>`, or only the address when the email has no name. */
+    from: string;
+    /** The recipients at this domain, in lowercase. */
+    to: string[];
+    cc: string[];
+    reply_to: string[];
+    /** The Message-ID header with its angle brackets, for In-Reply-To and References when you reply. */
+    message_id: string | null;
+    /** Empty when the email has no plain-text part. */
+    text: string;
+    /** Empty when the email has no HTML part. It is the sender's HTML: sanitize it before showing it. */
+    html: string;
+    /** `true` when the Amazon SES spam check flagged the email. */
+    spam: boolean;
+    attachments: ReceivedAttachment[];
+}
+/** `data` of an event about an email you sent: the email as it is now, plus the detail for that event. */
+export interface EmailEventData extends EmailFields {
+    direction: 'outbound';
+    status: string;
+    scheduled_at: string | null;
+    error: string | null;
+    /** The recipient the event is about. Not set on email.sent and email.failed, nor on opens and clicks of an email with more than one recipient. */
+    recipient?: string;
+    delivery?: {
+        smtp_response: string | null;
+    };
+    delay?: {
+        type: string | null;
+        expires_at: string | null;
+        message: string | null;
+    };
+    bounce?: {
+        type: 'Permanent' | 'Transient' | (string & {}) | null;
+        sub_type: string | null;
+        message: string | null;
+    };
+    complaint?: {
+        type: string | null;
+    };
+    open?: {
+        ip_address: string | null;
+        user_agent: string | null;
+    };
+    click?: {
+        link: string | null;
+        ip_address: string | null;
+        user_agent: string | null;
+    };
+    failed?: {
+        reason: string;
+    };
+}
+/** The event `verifyWebhook` returns. Check `event.type` and `event.data` has the matching fields. */
+export type MailumiWebhookEvent = {
+    id: string;
+    type: 'email.received';
+    created_at: string;
+    data: EmailReceivedData;
+} | {
+    id: string;
+    type: Exclude<WebhookEventType, 'email.received' | 'webhook.test'>;
+    created_at: string;
+    data: EmailEventData;
+} | {
+    id: string;
+    type: 'webhook.test';
+    created_at: string;
+    data: {
+        message: string;
+    };
+};
 export interface VerifyWebhookOptions {
     /** The raw request body exactly as received, before any JSON parsing. */
     payload: string | Uint8Array;
@@ -203,7 +424,8 @@ export interface VerifyWebhookOptions {
  * Checks the Standard Webhooks signature of a Mailumi webhook and returns the parsed event.
  * Store `event.id` and skip ids you have seen: a delivery can arrive more than once.
  */
-export declare function verifyWebhook<T = Record<string, any>>({ payload, headers, secret, tolerance }: VerifyWebhookOptions): Promise<Result<WebhookEvent<T>>>;
+export declare function verifyWebhook(options: VerifyWebhookOptions): Promise<Result<MailumiWebhookEvent>>;
+export declare function verifyWebhook<T>(options: VerifyWebhookOptions): Promise<Result<WebhookEvent<T>>>;
 /** Converts the SDK's camelCase options to the API's request body. snake_case keys are accepted too. */
 export declare function toApiEmail(o: SendEmailOptions & Record<string, any>): Record<string, unknown>;
 export declare class Mailumi {
@@ -247,6 +469,54 @@ export declare class Mailumi {
         list: () => Promise<Result<{
             data: Domain[];
         }>>;
+        /** Adds a domain and returns the DNS records to publish. Needs a key with access to all domains. */
+        create: ({ name }: {
+            name: string;
+        }) => Promise<Result<Domain>>;
+        get: (id: string) => Promise<Result<Domain>>;
+        /** Checks the DNS records now. Mailumi also checks new domains every 5 minutes and emails you once one is verified. */
+        verify: (id: string) => Promise<Result<DomainVerification>>;
+        update: ({ id, receivingEnabled, mxConsent, openTracking, clickTracking, ...rest }: DomainSettings & Record<string, any>) => Promise<Result<Domain>>;
+        /** Removes the domain. Emails can no longer be sent from it. */
+        remove: (id: string) => Promise<Result<Deleted>>;
+    };
+    readonly webhooks: {
+        /** Verifies a webhook signature. Needs no API key; `verifyWebhook` is also exported on its own. */
+        verify: typeof verifyWebhook;
+        list: () => Promise<Result<{
+            data: Webhook[];
+        }>>;
+        /** Creates a webhook. `secret` is only returned here: store it as MAILUMI_WEBHOOK_SECRET. */
+        create: (webhook: NewWebhook) => Promise<Result<Webhook & {
+            secret: string;
+        }>>;
+        get: (id: string) => Promise<Result<Webhook>>;
+        /** Stops sending events to the webhook. */
+        disable: (id: string) => Promise<Result<Webhook>>;
+        /** Sends a signed `webhook.test` event and returns the delivery. */
+        test: (id: string) => Promise<Result<WebhookDelivery>>;
+        /** The 100 most recent deliveries, newest first. */
+        deliveries: (id: string) => Promise<Result<{
+            data: WebhookDelivery[];
+        }>>;
+        /** Delivers an event again now. */
+        retry: ({ id, deliveryId }: {
+            id: string;
+            deliveryId: string;
+        }) => Promise<Result<WebhookDelivery>>;
+    };
+    readonly templates: {
+        list: () => Promise<Result<{
+            data: Template[];
+        }>>;
+        /** Saves a template to send with `templateId`. */
+        create: (template: NewTemplate) => Promise<Result<Template>>;
+        get: (id: string) => Promise<Result<Template>>;
+        /** Changes only the fields you pass. */
+        update: ({ id, ...template }: Partial<NewTemplate> & {
+            id: string;
+        }) => Promise<Result<Template>>;
+        remove: (id: string) => Promise<Result<Deleted>>;
     };
     readonly audiences: {
         list: () => Promise<Result<{
@@ -291,9 +561,38 @@ export declare class Mailumi {
         }) => Promise<Result<Contact>>;
         remove: (ref: ContactRef) => Promise<Result<Deleted>>;
     };
-    /** Verifies a webhook signature. Needs no API key; `verifyWebhook` is also exported on its own. */
-    readonly webhooks: {
-        verify: typeof verifyWebhook;
+    readonly campaigns: {
+        /** Lists campaigns, newest first, with delivery statistics for those that were sent. */
+        list: () => Promise<Result<{
+            data: Campaign[];
+        }>>;
+        /** Creates a draft. */
+        create: (campaign: NewCampaign) => Promise<Result<Campaign>>;
+        /** Drafts include `readiness`; sent campaigns include `stats`. */
+        get: (id: string) => Promise<Result<Campaign>>;
+        /** Changes only the fields you pass. Only drafts can be changed. */
+        update: ({ id, ...campaign }: Partial<NewCampaign> & {
+            id: string;
+        }) => Promise<Result<Campaign>>;
+        /** Sends a draft to every subscribed contact in its audience now. */
+        send: (id: string) => Promise<Result<Campaign>>;
+        /** Copies a campaign into a new draft. */
+        duplicate: (id: string) => Promise<Result<Campaign>>;
+        remove: (id: string) => Promise<Result<Deleted>>;
+    };
+    readonly suppressions: {
+        /** Addresses that bounced, complained or were added by hand. Mailumi does not send to them. */
+        list: (q?: {
+            search?: string;
+        }) => Promise<Result<{
+            data: Suppression[];
+        }>>;
+        /** Allows sending to the address again. */
+        remove: (address: string) => Promise<Result<{
+            object: "suppression";
+            address: string;
+            deleted: true;
+        }>>;
     };
     private readonly key;
     private readonly baseUrl;

package/dist/cjs/index.js

@@ -7,7 +7,7 @@ exports.toApiEmail = toApiEmail;
  * The official Mailumi SDK. Works anywhere `fetch` exists: Node.js 18+, Bun, Deno and Cloudflare Workers.
  * Every method resolves to `{ data, error }` and never throws for API errors.
  */
-exports.VERSION = '1.0.0';
+exports.VERSION = '1.2.0';
 const DEFAULT_BASE_URL = 'https://mailumi.com/api/v1';
 function header(h, name, short) {
     if (typeof h.get === 'function')
@@ -29,10 +29,6 @@ function sameText(a, b) {
         diff |= (a.charCodeAt(i) || 0) ^ (b.charCodeAt(i) || 0);
     return diff === 0;
 }
-/**
- * Checks the Standard Webhooks signature of a Mailumi webhook and returns the parsed event.
- * Store `event.id` and skip ids you have seen: a delivery can arrive more than once.
- */
 async function verifyWebhook({ payload, headers, secret, tolerance = 300 }) {
     const key = secret ?? globalThis.process?.env?.MAILUMI_WEBHOOK_SECRET;
     if (!key)
@@ -85,10 +81,11 @@ function toApiEmail(o) {
 }
 const toApiContact = (c) => ({ email: c.email, first_name: c.firstName ?? c.first_name, last_name: c.lastName ?? c.last_name, unsubscribed: c.unsubscribed });
 const contactPath = (r) => `/audiences/${encodeURIComponent(r.audienceId)}/contacts/${encodeURIComponent(r.id ?? r.email ?? '')}`;
+const toApiWebhook = (w) => ({ name: w.name, url: w.url, events: w.events, domain_id: w.domainId ?? w.domain_id, recipient: w.recipient });
+const toApiCampaign = (c) => ({ name: c.name, subject: c.subject, text: c.text, from: c.from, audience_id: c.audienceId !== undefined ? c.audienceId : c.audience_id });
+const pathTo = (base, id, rest = '') => `${base}/${encodeURIComponent(id)}${rest}`;
 class Mailumi {
     constructor(apiKey, options = {}) {
-        /** Verifies a webhook signature. Needs no API key; `verifyWebhook` is also exported on its own. */
-        this.webhooks = { verify: verifyWebhook };
         const env = globalThis.process?.env ?? {};
         this.key = apiKey ?? env.MAILUMI_API_KEY ?? '';
         this.baseUrl = (options.baseUrl ?? env.MAILUMI_BASE_URL ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
@@ -116,6 +113,62 @@ class Mailumi {
         this.domains = {
             /** Lists your domains, their DNS records and whether each is verified. */
             list: () => this.request('GET', '/domains'),
+            /** Adds a domain and returns the DNS records to publish. Needs a key with access to all domains. */
+            create: ({ name }) => this.request('POST', '/domains', { name }),
+            get: (id) => this.request('GET', pathTo('/domains', id)),
+            /** Checks the DNS records now. Mailumi also checks new domains every 5 minutes and emails you once one is verified. */
+            verify: (id) => this.request('POST', pathTo('/domains', id, '/verify')),
+            update: ({ id, receivingEnabled, mxConsent, openTracking, clickTracking, ...rest }) => this.request('PATCH', pathTo('/domains', id), {
+                receiving_enabled: receivingEnabled ?? rest.receiving_enabled, mx_consent: mxConsent ?? rest.mx_consent, open_tracking: openTracking ?? rest.open_tracking, click_tracking: clickTracking ?? rest.click_tracking,
+            }),
+            /** Removes the domain. Emails can no longer be sent from it. */
+            remove: (id) => this.request('DELETE', pathTo('/domains', id)),
+        };
+        this.webhooks = {
+            /** Verifies a webhook signature. Needs no API key; `verifyWebhook` is also exported on its own. */
+            verify: verifyWebhook,
+            list: () => this.request('GET', '/webhooks'),
+            /** Creates a webhook. `secret` is only returned here: store it as MAILUMI_WEBHOOK_SECRET. */
+            create: (webhook) => this.request('POST', '/webhooks', toApiWebhook(webhook)),
+            get: (id) => this.request('GET', pathTo('/webhooks', id)),
+            /** Stops sending events to the webhook. */
+            disable: (id) => this.request('DELETE', pathTo('/webhooks', id)),
+            /** Sends a signed `webhook.test` event and returns the delivery. */
+            test: (id) => this.request('POST', pathTo('/webhooks', id, '/test')),
+            /** The 100 most recent deliveries, newest first. */
+            deliveries: (id) => this.request('GET', pathTo('/webhooks', id, '/deliveries')),
+            /** Delivers an event again now. */
+            retry: ({ id, deliveryId }) => this.request('POST', pathTo('/webhooks', id, `/deliveries/${encodeURIComponent(deliveryId)}/retry`)),
+        };
+        this.templates = {
+            list: () => this.request('GET', '/templates'),
+            /** Saves a template to send with `templateId`. */
+            create: (template) => this.request('POST', '/templates', template),
+            get: (id) => this.request('GET', pathTo('/templates', id)),
+            /** Changes only the fields you pass. */
+            update: ({ id, ...template }) => this.request('PATCH', pathTo('/templates', id), template),
+            remove: (id) => this.request('DELETE', pathTo('/templates', id)),
+        };
+        this.campaigns = {
+            /** Lists campaigns, newest first, with delivery statistics for those that were sent. */
+            list: () => this.request('GET', '/campaigns'),
+            /** Creates a draft. */
+            create: (campaign) => this.request('POST', '/campaigns', toApiCampaign(campaign)),
+            /** Drafts include `readiness`; sent campaigns include `stats`. */
+            get: (id) => this.request('GET', pathTo('/campaigns', id)),
+            /** Changes only the fields you pass. Only drafts can be changed. */
+            update: ({ id, ...campaign }) => this.request('PATCH', pathTo('/campaigns', id), toApiCampaign(campaign)),
+            /** Sends a draft to every subscribed contact in its audience now. */
+            send: (id) => this.request('POST', pathTo('/campaigns', id, '/send')),
+            /** Copies a campaign into a new draft. */
+            duplicate: (id) => this.request('POST', pathTo('/campaigns', id, '/duplicate')),
+            remove: (id) => this.request('DELETE', pathTo('/campaigns', id)),
+        };
+        this.suppressions = {
+            /** Addresses that bounced, complained or were added by hand. Mailumi does not send to them. */
+            list: (q = {}) => this.request('GET', '/suppressions' + query(q)),
+            /** Allows sending to the address again. */
+            remove: (address) => this.request('DELETE', pathTo('/suppressions', address)),
         };
         this.audiences = {
             list: () => this.request('GET', '/audiences'),

package/dist/cli.js

@@ -13,11 +13,36 @@ Commands
   emails cancel <id>           Cancel a scheduled email
   emails reschedule <id> <at>  Change the send time: an ISO 8601 date or "in 2 hours"
   domains list                 List domains and their verification status
+  domains add <name>           Add a domain and show the DNS records to publish
+  domains get <id>             Show a domain's DNS records and which were found
+  domains verify <id>          Check the DNS records now (--wait: re-check every 15 seconds until verified)
+  domains update <id>          --receiving on|off [--mx-consent], --open-tracking on|off, --click-tracking on|off
+  domains remove <id>          Remove a domain
+  webhooks list                List webhooks
+  webhooks create <url>        --name <name> [--events email.delivered,email.bounced] [--domain <id>] [--recipient <name>]
+  webhooks test <id>           Send a signed test event
+  webhooks deliveries <id>     Show the latest deliveries
+  webhooks retry <id> <delivery_id>
+  webhooks disable <id>        Stop sending events to a webhook
+  templates list               List templates
+  templates get <id>           Show a template
+  templates create             --name <name> --subject <text> --html <html> | --html-file <path> [--var name=default]
+  templates update <id>        Change any of --name, --subject, --html, --html-file, --var
+  templates remove <id>        Delete a template
   audiences list               List audiences
   audiences create <name>      Create an audience
   contacts list <audience>     List contacts (--search <text>, --after <cursor>)
   contacts add <audience> <email> [--first-name <name>] [--last-name <name>]
   contacts unsubscribe <audience> <email>
+  campaigns list               List campaigns with their results
+  campaigns get <id>           Show a campaign, and what is missing before a draft can be sent
+  campaigns create             --name <name> --subject <text> --text <text> | --text-file <path> [--from <address>] [--audience <id>]
+  campaigns update <id>        Change any of --name, --subject, --text, --text-file, --from, --audience
+  campaigns send <id>          Send a draft to its audience now
+  campaigns duplicate <id>     Copy a campaign into a new draft
+  campaigns remove <id>        Delete a campaign
+  suppressions list            List suppressed addresses (--search <text>)
+  suppressions remove <address>  Allow sending to an address again
 
 Send options
   --from <address>             Sender on a verified domain, e.g. "Acme <hello@yourdomain.com>"
@@ -37,7 +62,7 @@ Global options
   --help, --version
 
 Docs: https://mailumi.com/docs`;
-const BOOLEAN = new Set(['json', 'help', 'version', 'inbound', 'outbound']);
+const BOOLEAN = new Set(['json', 'help', 'version', 'inbound', 'outbound', 'wait', 'mx-consent']);
 function parse(argv) {
     const args = [], flags = {};
     for (let i = 0; i < argv.length; i++) {
@@ -87,6 +112,28 @@ function sendOptions(f) {
         variables: pairs(f, 'var') && Object.fromEntries(pairs(f, 'var')), tags: pairs(f, 'tag')?.map(([name, value]) => ({ name, value })),
     };
 }
+function toggle(f, name) {
+    const v = one(f, name);
+    if (v === undefined)
+        return undefined;
+    if (/^(on|true|yes)$/i.test(v))
+        return true;
+    if (/^(off|false|no)$/i.test(v))
+        return false;
+    throw new Error(`--${name} expects on or off, got "${v}".`);
+}
+const fileOr = (f, name) => one(f, name) ?? (one(f, `${name}-file`) ? readFileSync(one(f, `${name}-file`), 'utf8') : undefined);
+function templateOptions(f) {
+    const variables = pairs(f, 'var');
+    return { name: one(f, 'name'), subject: one(f, 'subject'), html: fileOr(f, 'html'), variables: variables && Object.fromEntries(variables) };
+}
+const campaignOptions = (f) => ({ name: one(f, 'name'), subject: one(f, 'subject'), text: fileOr(f, 'text'), from: one(f, 'from'), audienceId: one(f, 'audience') });
+const recordList = (d) => d.records.map(r => {
+    const state = r.verified ? 'found' : r.found?.length ? `wrong value, found ${r.found.join(', ')}` : 'missing';
+    return `[${state}] ${r.type} ${r.name}${r.required ? '' : ' (recommended)'}\n    ${r.priority !== undefined ? `${r.priority} ` : ''}${r.value}`;
+}).join('\n');
+const domainView = (d) => `${d.name} (${d.id}): ${d.sendingStatus === 'verified' ? 'verified, ready to send' : d.sendingStatus}\n\n${recordList(d)}`;
+const KEEPS_CHECKING = 'Mailumi keeps checking every 5 minutes and emails you once the domain is verified.';
 const table = (rows, columns) => {
     if (!rows.length)
         return '(none)';
@@ -134,6 +181,100 @@ async function run(argv) {
             result = await client.domains.list();
             print = l => table(l.data, ['name', 'sendingStatus', 'receivingStatus', 'id']);
             break;
+        case 'domains add':
+            need(1, 'domains add <name>');
+            result = await client.domains.create({ name: rest[0] });
+            print = d => `Added ${d.name} (${d.id}). Publish these DNS records at your DNS provider:\n\n${recordList(d)}\n\nThen run: mailumi domains verify ${d.id} --wait`;
+            break;
+        case 'domains get':
+            need(1, 'domains get <id>');
+            result = await client.domains.get(rest[0]);
+            print = domainView;
+            break;
+        case 'domains verify': {
+            need(1, 'domains verify <id> [--wait]');
+            const until = Date.now() + 30 * 60000;
+            for (;;) {
+                result = await client.domains.verify(rest[0]);
+                if (!flags.wait || result.error || result.data.ready || result.data.domain.sendingStatus === 'failed' || Date.now() > until)
+                    break;
+                if (!json)
+                    console.error(`${result.data.message} Checking again in 15 seconds…`);
+                await new Promise(r => setTimeout(r, 15000));
+            }
+            print = v => `${v.message}\n\n${domainView(v.domain)}${v.ready ? '' : `\n\n${KEEPS_CHECKING}`}`;
+            break;
+        }
+        case 'domains update':
+            need(1, 'domains update <id> [--receiving on|off] [--mx-consent] [--open-tracking on|off] [--click-tracking on|off]');
+            result = await client.domains.update({ id: rest[0], receivingEnabled: toggle(flags, 'receiving'), mxConsent: flags['mx-consent'] ? true : undefined, openTracking: toggle(flags, 'open-tracking'), clickTracking: toggle(flags, 'click-tracking') });
+            print = d => `Updated ${d.name}: receiving ${d.receivingEnabled ? 'on' : 'off'}, open tracking ${d.openTracking ? 'on' : 'off'}, click tracking ${d.clickTracking ? 'on' : 'off'}.`;
+            break;
+        case 'domains remove':
+            need(1, 'domains remove <id>');
+            result = await client.domains.remove(rest[0]);
+            print = d => `Removed domain ${d.id}.`;
+            break;
+        case 'webhooks list':
+            result = await client.webhooks.list();
+            print = l => table(l.data, ['id', 'name', 'url', 'events', 'enabled']);
+            break;
+        case 'webhooks create': {
+            need(1, 'webhooks create <url> --name <name>');
+            const name = one(flags, 'name');
+            if (!name)
+                throw new Error('webhooks create needs --name.');
+            result = await client.webhooks.create({ url: rest[0], name, events: many(flags, 'events'), domainId: one(flags, 'domain'), recipient: one(flags, 'recipient') });
+            print = w => `Created webhook ${w.name} (${w.id}) for ${w.events.join(', ')}.\n\nSigning secret, shown only now. Store it as MAILUMI_WEBHOOK_SECRET:\n${w.secret}\n\nSend a test event with: mailumi webhooks test ${w.id}`;
+            break;
+        }
+        case 'webhooks test':
+            need(1, 'webhooks test <id>');
+            result = await client.webhooks.test(rest[0]);
+            print = d => d.status === 'delivered' ? `Delivered test event ${d.id} (HTTP ${d.response_code}).` : `The test event ${d.id} is ${d.status}${d.response_code ? ` (HTTP ${d.response_code})` : ''}${d.last_error ? `: ${d.last_error}` : ''}.${d.next_attempt_at ? ` Next attempt at ${d.next_attempt_at}.` : ''}`;
+            break;
+        case 'webhooks deliveries':
+            need(1, 'webhooks deliveries <id>');
+            result = await client.webhooks.deliveries(rest[0]);
+            print = l => table(l.data, ['id', 'event', 'status', 'attempts', 'response_code', 'created_at']);
+            break;
+        case 'webhooks retry':
+            need(2, 'webhooks retry <id> <delivery_id>');
+            result = await client.webhooks.retry({ id: rest[0], deliveryId: rest[1] });
+            print = d => `Delivery ${d.id} is ${d.status}${d.response_code ? ` (HTTP ${d.response_code})` : ''}.`;
+            break;
+        case 'webhooks disable':
+            need(1, 'webhooks disable <id>');
+            result = await client.webhooks.disable(rest[0]);
+            print = w => `Disabled webhook ${w.name} (${w.id}).`;
+            break;
+        case 'templates list':
+            result = await client.templates.list();
+            print = l => table(l.data, ['id', 'name', 'subject', 'updated_at']);
+            break;
+        case 'templates get':
+            need(1, 'templates get <id>');
+            result = await client.templates.get(rest[0]);
+            print = t => [`${t.name} (${t.id})`, `Subject: ${t.subject}`, `Variables: ${Object.entries(t.variables).map(([k, v]) => v ? `${k}=${v}` : k).join(', ') || 'none'}`, '', t.html].join('\n');
+            break;
+        case 'templates create': {
+            const t = templateOptions(flags);
+            if (!t.name || !t.subject || !t.html)
+                throw new Error('templates create needs --name, --subject and --html or --html-file.');
+            result = await client.templates.create({ ...t, name: t.name, subject: t.subject, html: t.html });
+            print = t => `Created template ${t.name} (${t.id}). Send it with: mailumi send --template ${t.id} --from <address> --to <address>`;
+            break;
+        }
+        case 'templates update':
+            need(1, 'templates update <id>');
+            result = await client.templates.update({ id: rest[0], ...templateOptions(flags) });
+            print = t => `Updated template ${t.name} (${t.id}).`;
+            break;
+        case 'templates remove':
+            need(1, 'templates remove <id>');
+            result = await client.templates.remove(rest[0]);
+            print = t => `Deleted template ${t.id}.`;
+            break;
         case 'audiences list':
             result = await client.audiences.list();
             print = l => table(l.data, ['id', 'name', 'contacts', 'subscribed']);
@@ -158,6 +299,54 @@ async function run(argv) {
             result = await client.contacts.update({ audienceId: rest[0], email: rest[1], unsubscribed: true });
             print = c => `Unsubscribed ${c.email} from every audience.`;
             break;
+        case 'campaigns list':
+            result = await client.campaigns.list();
+            print = l => table(l.data.map((c) => ({ ...c, delivered: c.stats?.delivered ?? '' })), ['id', 'name', 'status', 'recipients', 'delivered', 'updated_at']);
+            break;
+        case 'campaigns get':
+            need(1, 'campaigns get <id>');
+            result = await client.campaigns.get(rest[0]);
+            print = c => [`${c.name} (${c.id}): ${c.status}`, `From: ${c.from ?? 'not set'}`, `Audience: ${c.audience_id ?? 'not set'}`, `Subject: ${c.subject}`,
+                ...(c.readiness ? ['', c.readiness.missing.length ? `Before sending: ${c.readiness.missing.join(' ')}` : `Ready to send to ${c.readiness.recipients} contacts: mailumi campaigns send ${c.id}`] : []),
+                ...(c.stats ? ['', Object.entries(c.stats).map(([k, v]) => `${k} ${v}`).join(', ')] : []), '', c.text].join('\n');
+            break;
+        case 'campaigns create': {
+            const c = campaignOptions(flags);
+            if (!c.name || !c.subject || !c.text)
+                throw new Error('campaigns create needs --name, --subject and --text or --text-file.');
+            result = await client.campaigns.create({ ...c, name: c.name, subject: c.subject, text: c.text });
+            print = c => `Created draft ${c.name} (${c.id}). Check it with: mailumi campaigns get ${c.id}`;
+            break;
+        }
+        case 'campaigns update':
+            need(1, 'campaigns update <id>');
+            result = await client.campaigns.update({ id: rest[0], ...campaignOptions(flags) });
+            print = c => `Updated draft ${c.name} (${c.id}).`;
+            break;
+        case 'campaigns send':
+            need(1, 'campaigns send <id>');
+            result = await client.campaigns.send(rest[0]);
+            print = c => `Sending ${c.name} to ${c.recipients} contacts. Follow it with: mailumi campaigns get ${c.id}`;
+            break;
+        case 'campaigns duplicate':
+            need(1, 'campaigns duplicate <id>');
+            result = await client.campaigns.duplicate(rest[0]);
+            print = c => `Created draft ${c.name} (${c.id}).`;
+            break;
+        case 'campaigns remove':
+            need(1, 'campaigns remove <id>');
+            result = await client.campaigns.remove(rest[0]);
+            print = c => `Deleted campaign ${c.id}.`;
+            break;
+        case 'suppressions list':
+            result = await client.suppressions.list({ search: one(flags, 'search') });
+            print = l => table(l.data, ['address', 'reason', 'detail', 'created_at']);
+            break;
+        case 'suppressions remove':
+            need(1, 'suppressions remove <address>');
+            result = await client.suppressions.remove(rest[0]);
+            print = s => `Mailumi will send to ${s.address} again.`;
+            break;
         default:
             throw new Error(`Unknown command "${args.join(' ')}". Run "mailumi --help".`);
     }

package/dist/index.d.ts

@@ -2,7 +2,7 @@
  * The official Mailumi SDK. Works anywhere `fetch` exists: Node.js 18+, Bun, Deno and Cloudflare Workers.
  * Every method resolves to `{ data, error }` and never throws for API errors.
  */
-export declare const VERSION = "1.0.0";
+export declare const VERSION = "1.2.0";
 export type ErrorCode = 'invalid_request' | 'unauthorized' | 'plan_limit_reached' | 'forbidden' | 'not_found' | 'method_not_allowed' | 'conflict' | 'payload_too_large' | 'rate_limited' | 'internal_error' | 'service_unavailable' | 'network_error' | 'missing_api_key' | 'invalid_signature' | 'missing_webhook_secret';
 export interface MailumiError {
     name: 'MailumiError';
@@ -116,10 +116,13 @@ export interface DnsRecord {
     value: string;
     priority?: number;
     verified: boolean;
+    /** What DNS returned at this name when it does not match `value`. Only on records that are not verified. */
+    found?: string[];
 }
 export interface Domain {
     id: string;
     name: string;
+    region?: string;
     ownershipVerified?: boolean;
     sendingEnabled?: boolean;
     receivingEnabled?: boolean;
@@ -131,6 +134,125 @@ export interface Domain {
     createdAt?: number;
     records: DnsRecord[];
 }
+export interface DomainVerification {
+    domain: Domain;
+    /** `true` once the domain can send. */
+    ready: boolean;
+    /** What is still missing, or that the domain is ready. */
+    message: string;
+    /** How many required records have a different value at the DNS provider. */
+    wrong?: number;
+}
+export interface DomainSettings {
+    id: string;
+    /** Receive email for the domain and send it to your email.received webhooks. */
+    receivingEnabled?: boolean;
+    /** Must be `true` to turn receiving on: the MX record replaces any mailbox provider the domain uses now. */
+    mxConsent?: boolean;
+    /** Pro and Scale plans. */
+    openTracking?: boolean;
+    /** Pro and Scale plans. */
+    clickTracking?: boolean;
+}
+export type WebhookSubscription = Exclude<WebhookEventType, 'webhook.test'>;
+export interface NewWebhook {
+    name: string;
+    /** A public HTTPS URL on port 443. */
+    url: string;
+    /** Defaults to `['email.received']`. */
+    events?: WebhookSubscription[];
+    /** Only send events for this domain. Leave it out for every domain. */
+    domainId?: string;
+    /** For email.received: only mail to this address before the @, for example "support". */
+    recipient?: string;
+}
+export interface Webhook {
+    object: 'webhook';
+    id: string;
+    name: string;
+    url: string;
+    events: WebhookSubscription[];
+    domain_id: string | null;
+    recipient: string | null;
+    enabled: boolean;
+    created_at: string;
+}
+export interface WebhookDelivery {
+    /** Also the webhook-id header of the request. */
+    id: string;
+    object: 'webhook_delivery';
+    webhook_id: string;
+    event: WebhookEventType;
+    email_id: string | null;
+    status: 'pending' | 'delivered' | 'failed' | 'cancelled';
+    attempts: number;
+    response_code: number | null;
+    last_error: string | null;
+    next_attempt_at: string | null;
+    created_at: string;
+    delivered_at: string | null;
+}
+export interface NewTemplate {
+    name: string;
+    /** Placeholders such as `{{first_name}}` work in the subject and HTML. */
+    subject: string;
+    html: string;
+    /** Default values for placeholders an email does not pass. */
+    variables?: Record<string, string>;
+}
+export interface Template {
+    object: 'template';
+    id: string;
+    name: string;
+    subject: string;
+    html: string;
+    variables: Record<string, string>;
+    created_at: string;
+    updated_at: string;
+}
+export interface NewCampaign {
+    name: string;
+    /** `{{first_name}}`, `{{last_name}}` and `{{email}}` are filled in per contact. */
+    subject: string;
+    /** Plain text. Blank lines start paragraphs and links become clickable. Mailumi adds your postal address and an unsubscribe link. */
+    text: string;
+    /** A sender on a verified domain. Needed before sending. */
+    from?: string;
+    /** Needed before sending. */
+    audienceId?: string | null;
+}
+export type CampaignStats = Record<'total' | 'pending' | 'sent' | 'delivered' | 'bounced' | 'complained' | 'failed' | 'suppressed' | 'opened' | 'clicked' | 'unsubscribed', number>;
+export interface Campaign {
+    object: 'campaign';
+    id: string;
+    name: string;
+    subject: string;
+    text: string;
+    from: string | null;
+    audience_id: string | null;
+    status: 'draft' | 'sending' | 'sent' | 'failed';
+    /** How many contacts it was sent to. */
+    recipients: number;
+    error: string | null;
+    sent_at: string | null;
+    created_at: string;
+    updated_at: string;
+    /** Drafts, from `campaigns.get`: how many contacts it would go to now, and what to fix before sending. */
+    readiness?: {
+        recipients: number;
+        missing: string[];
+    };
+    /** Campaigns that were sent. */
+    stats?: CampaignStats;
+}
+export interface Suppression {
+    object: 'suppression';
+    address: string;
+    reason: 'bounce' | 'complaint' | 'manual';
+    detail: string | null;
+    email_id: string | null;
+    created_at: string;
+}
 export interface Audience {
     object: 'audience';
     id: string;
@@ -189,6 +311,105 @@ export interface WebhookEvent<T = Record<string, any>> {
     created_at: string;
     data: T;
 }
+interface EmailFields {
+    email_id: string;
+    domain_id: string;
+    from: string;
+    to: string[];
+    subject: string;
+    last_event: string;
+    tags: Record<string, string>;
+    created_at: string;
+}
+export interface ReceivedAttachment {
+    id: string;
+    filename: string;
+    content_type: string;
+    /** Set for inline images that the HTML shows with `cid:`. */
+    content_id: string | null;
+    /** Size in bytes. */
+    size: number;
+    /** Download it server-side with `mailumi.emails.attachment({ id: email_id, index })` or a key with email:read. */
+    download_url: string;
+}
+/** `data` of an `email.received` event. */
+export interface EmailReceivedData extends EmailFields {
+    direction: 'inbound';
+    status: 'received';
+    scheduled_at: null;
+    error: null;
+    /** `Name <address>`, or only the address when the email has no name. */
+    from: string;
+    /** The recipients at this domain, in lowercase. */
+    to: string[];
+    cc: string[];
+    reply_to: string[];
+    /** The Message-ID header with its angle brackets, for In-Reply-To and References when you reply. */
+    message_id: string | null;
+    /** Empty when the email has no plain-text part. */
+    text: string;
+    /** Empty when the email has no HTML part. It is the sender's HTML: sanitize it before showing it. */
+    html: string;
+    /** `true` when the Amazon SES spam check flagged the email. */
+    spam: boolean;
+    attachments: ReceivedAttachment[];
+}
+/** `data` of an event about an email you sent: the email as it is now, plus the detail for that event. */
+export interface EmailEventData extends EmailFields {
+    direction: 'outbound';
+    status: string;
+    scheduled_at: string | null;
+    error: string | null;
+    /** The recipient the event is about. Not set on email.sent and email.failed, nor on opens and clicks of an email with more than one recipient. */
+    recipient?: string;
+    delivery?: {
+        smtp_response: string | null;
+    };
+    delay?: {
+        type: string | null;
+        expires_at: string | null;
+        message: string | null;
+    };
+    bounce?: {
+        type: 'Permanent' | 'Transient' | (string & {}) | null;
+        sub_type: string | null;
+        message: string | null;
+    };
+    complaint?: {
+        type: string | null;
+    };
+    open?: {
+        ip_address: string | null;
+        user_agent: string | null;
+    };
+    click?: {
+        link: string | null;
+        ip_address: string | null;
+        user_agent: string | null;
+    };
+    failed?: {
+        reason: string;
+    };
+}
+/** The event `verifyWebhook` returns. Check `event.type` and `event.data` has the matching fields. */
+export type MailumiWebhookEvent = {
+    id: string;
+    type: 'email.received';
+    created_at: string;
+    data: EmailReceivedData;
+} | {
+    id: string;
+    type: Exclude<WebhookEventType, 'email.received' | 'webhook.test'>;
+    created_at: string;
+    data: EmailEventData;
+} | {
+    id: string;
+    type: 'webhook.test';
+    created_at: string;
+    data: {
+        message: string;
+    };
+};
 export interface VerifyWebhookOptions {
     /** The raw request body exactly as received, before any JSON parsing. */
     payload: string | Uint8Array;
@@ -203,7 +424,8 @@ export interface VerifyWebhookOptions {
  * Checks the Standard Webhooks signature of a Mailumi webhook and returns the parsed event.
  * Store `event.id` and skip ids you have seen: a delivery can arrive more than once.
  */
-export declare function verifyWebhook<T = Record<string, any>>({ payload, headers, secret, tolerance }: VerifyWebhookOptions): Promise<Result<WebhookEvent<T>>>;
+export declare function verifyWebhook(options: VerifyWebhookOptions): Promise<Result<MailumiWebhookEvent>>;
+export declare function verifyWebhook<T>(options: VerifyWebhookOptions): Promise<Result<WebhookEvent<T>>>;
 /** Converts the SDK's camelCase options to the API's request body. snake_case keys are accepted too. */
 export declare function toApiEmail(o: SendEmailOptions & Record<string, any>): Record<string, unknown>;
 export declare class Mailumi {
@@ -247,6 +469,54 @@ export declare class Mailumi {
         list: () => Promise<Result<{
             data: Domain[];
         }>>;
+        /** Adds a domain and returns the DNS records to publish. Needs a key with access to all domains. */
+        create: ({ name }: {
+            name: string;
+        }) => Promise<Result<Domain>>;
+        get: (id: string) => Promise<Result<Domain>>;
+        /** Checks the DNS records now. Mailumi also checks new domains every 5 minutes and emails you once one is verified. */
+        verify: (id: string) => Promise<Result<DomainVerification>>;
+        update: ({ id, receivingEnabled, mxConsent, openTracking, clickTracking, ...rest }: DomainSettings & Record<string, any>) => Promise<Result<Domain>>;
+        /** Removes the domain. Emails can no longer be sent from it. */
+        remove: (id: string) => Promise<Result<Deleted>>;
+    };
+    readonly webhooks: {
+        /** Verifies a webhook signature. Needs no API key; `verifyWebhook` is also exported on its own. */
+        verify: typeof verifyWebhook;
+        list: () => Promise<Result<{
+            data: Webhook[];
+        }>>;
+        /** Creates a webhook. `secret` is only returned here: store it as MAILUMI_WEBHOOK_SECRET. */
+        create: (webhook: NewWebhook) => Promise<Result<Webhook & {
+            secret: string;
+        }>>;
+        get: (id: string) => Promise<Result<Webhook>>;
+        /** Stops sending events to the webhook. */
+        disable: (id: string) => Promise<Result<Webhook>>;
+        /** Sends a signed `webhook.test` event and returns the delivery. */
+        test: (id: string) => Promise<Result<WebhookDelivery>>;
+        /** The 100 most recent deliveries, newest first. */
+        deliveries: (id: string) => Promise<Result<{
+            data: WebhookDelivery[];
+        }>>;
+        /** Delivers an event again now. */
+        retry: ({ id, deliveryId }: {
+            id: string;
+            deliveryId: string;
+        }) => Promise<Result<WebhookDelivery>>;
+    };
+    readonly templates: {
+        list: () => Promise<Result<{
+            data: Template[];
+        }>>;
+        /** Saves a template to send with `templateId`. */
+        create: (template: NewTemplate) => Promise<Result<Template>>;
+        get: (id: string) => Promise<Result<Template>>;
+        /** Changes only the fields you pass. */
+        update: ({ id, ...template }: Partial<NewTemplate> & {
+            id: string;
+        }) => Promise<Result<Template>>;
+        remove: (id: string) => Promise<Result<Deleted>>;
     };
     readonly audiences: {
         list: () => Promise<Result<{
@@ -291,9 +561,38 @@ export declare class Mailumi {
         }) => Promise<Result<Contact>>;
         remove: (ref: ContactRef) => Promise<Result<Deleted>>;
     };
-    /** Verifies a webhook signature. Needs no API key; `verifyWebhook` is also exported on its own. */
-    readonly webhooks: {
-        verify: typeof verifyWebhook;
+    readonly campaigns: {
+        /** Lists campaigns, newest first, with delivery statistics for those that were sent. */
+        list: () => Promise<Result<{
+            data: Campaign[];
+        }>>;
+        /** Creates a draft. */
+        create: (campaign: NewCampaign) => Promise<Result<Campaign>>;
+        /** Drafts include `readiness`; sent campaigns include `stats`. */
+        get: (id: string) => Promise<Result<Campaign>>;
+        /** Changes only the fields you pass. Only drafts can be changed. */
+        update: ({ id, ...campaign }: Partial<NewCampaign> & {
+            id: string;
+        }) => Promise<Result<Campaign>>;
+        /** Sends a draft to every subscribed contact in its audience now. */
+        send: (id: string) => Promise<Result<Campaign>>;
+        /** Copies a campaign into a new draft. */
+        duplicate: (id: string) => Promise<Result<Campaign>>;
+        remove: (id: string) => Promise<Result<Deleted>>;
+    };
+    readonly suppressions: {
+        /** Addresses that bounced, complained or were added by hand. Mailumi does not send to them. */
+        list: (q?: {
+            search?: string;
+        }) => Promise<Result<{
+            data: Suppression[];
+        }>>;
+        /** Allows sending to the address again. */
+        remove: (address: string) => Promise<Result<{
+            object: "suppression";
+            address: string;
+            deleted: true;
+        }>>;
     };
     private readonly key;
     private readonly baseUrl;

package/dist/index.js

@@ -2,7 +2,7 @@
  * The official Mailumi SDK. Works anywhere `fetch` exists: Node.js 18+, Bun, Deno and Cloudflare Workers.
  * Every method resolves to `{ data, error }` and never throws for API errors.
  */
-export const VERSION = '1.0.0';
+export const VERSION = '1.2.0';
 const DEFAULT_BASE_URL = 'https://mailumi.com/api/v1';
 function header(h, name, short) {
     if (typeof h.get === 'function')
@@ -24,10 +24,6 @@ function sameText(a, b) {
         diff |= (a.charCodeAt(i) || 0) ^ (b.charCodeAt(i) || 0);
     return diff === 0;
 }
-/**
- * Checks the Standard Webhooks signature of a Mailumi webhook and returns the parsed event.
- * Store `event.id` and skip ids you have seen: a delivery can arrive more than once.
- */
 export async function verifyWebhook({ payload, headers, secret, tolerance = 300 }) {
     const key = secret ?? globalThis.process?.env?.MAILUMI_WEBHOOK_SECRET;
     if (!key)
@@ -80,10 +76,11 @@ export function toApiEmail(o) {
 }
 const toApiContact = (c) => ({ email: c.email, first_name: c.firstName ?? c.first_name, last_name: c.lastName ?? c.last_name, unsubscribed: c.unsubscribed });
 const contactPath = (r) => `/audiences/${encodeURIComponent(r.audienceId)}/contacts/${encodeURIComponent(r.id ?? r.email ?? '')}`;
+const toApiWebhook = (w) => ({ name: w.name, url: w.url, events: w.events, domain_id: w.domainId ?? w.domain_id, recipient: w.recipient });
+const toApiCampaign = (c) => ({ name: c.name, subject: c.subject, text: c.text, from: c.from, audience_id: c.audienceId !== undefined ? c.audienceId : c.audience_id });
+const pathTo = (base, id, rest = '') => `${base}/${encodeURIComponent(id)}${rest}`;
 export class Mailumi {
     constructor(apiKey, options = {}) {
-        /** Verifies a webhook signature. Needs no API key; `verifyWebhook` is also exported on its own. */
-        this.webhooks = { verify: verifyWebhook };
         const env = globalThis.process?.env ?? {};
         this.key = apiKey ?? env.MAILUMI_API_KEY ?? '';
         this.baseUrl = (options.baseUrl ?? env.MAILUMI_BASE_URL ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
@@ -111,6 +108,62 @@ export class Mailumi {
         this.domains = {
             /** Lists your domains, their DNS records and whether each is verified. */
             list: () => this.request('GET', '/domains'),
+            /** Adds a domain and returns the DNS records to publish. Needs a key with access to all domains. */
+            create: ({ name }) => this.request('POST', '/domains', { name }),
+            get: (id) => this.request('GET', pathTo('/domains', id)),
+            /** Checks the DNS records now. Mailumi also checks new domains every 5 minutes and emails you once one is verified. */
+            verify: (id) => this.request('POST', pathTo('/domains', id, '/verify')),
+            update: ({ id, receivingEnabled, mxConsent, openTracking, clickTracking, ...rest }) => this.request('PATCH', pathTo('/domains', id), {
+                receiving_enabled: receivingEnabled ?? rest.receiving_enabled, mx_consent: mxConsent ?? rest.mx_consent, open_tracking: openTracking ?? rest.open_tracking, click_tracking: clickTracking ?? rest.click_tracking,
+            }),
+            /** Removes the domain. Emails can no longer be sent from it. */
+            remove: (id) => this.request('DELETE', pathTo('/domains', id)),
+        };
+        this.webhooks = {
+            /** Verifies a webhook signature. Needs no API key; `verifyWebhook` is also exported on its own. */
+            verify: verifyWebhook,
+            list: () => this.request('GET', '/webhooks'),
+            /** Creates a webhook. `secret` is only returned here: store it as MAILUMI_WEBHOOK_SECRET. */
+            create: (webhook) => this.request('POST', '/webhooks', toApiWebhook(webhook)),
+            get: (id) => this.request('GET', pathTo('/webhooks', id)),
+            /** Stops sending events to the webhook. */
+            disable: (id) => this.request('DELETE', pathTo('/webhooks', id)),
+            /** Sends a signed `webhook.test` event and returns the delivery. */
+            test: (id) => this.request('POST', pathTo('/webhooks', id, '/test')),
+            /** The 100 most recent deliveries, newest first. */
+            deliveries: (id) => this.request('GET', pathTo('/webhooks', id, '/deliveries')),
+            /** Delivers an event again now. */
+            retry: ({ id, deliveryId }) => this.request('POST', pathTo('/webhooks', id, `/deliveries/${encodeURIComponent(deliveryId)}/retry`)),
+        };
+        this.templates = {
+            list: () => this.request('GET', '/templates'),
+            /** Saves a template to send with `templateId`. */
+            create: (template) => this.request('POST', '/templates', template),
+            get: (id) => this.request('GET', pathTo('/templates', id)),
+            /** Changes only the fields you pass. */
+            update: ({ id, ...template }) => this.request('PATCH', pathTo('/templates', id), template),
+            remove: (id) => this.request('DELETE', pathTo('/templates', id)),
+        };
+        this.campaigns = {
+            /** Lists campaigns, newest first, with delivery statistics for those that were sent. */
+            list: () => this.request('GET', '/campaigns'),
+            /** Creates a draft. */
+            create: (campaign) => this.request('POST', '/campaigns', toApiCampaign(campaign)),
+            /** Drafts include `readiness`; sent campaigns include `stats`. */
+            get: (id) => this.request('GET', pathTo('/campaigns', id)),
+            /** Changes only the fields you pass. Only drafts can be changed. */
+            update: ({ id, ...campaign }) => this.request('PATCH', pathTo('/campaigns', id), toApiCampaign(campaign)),
+            /** Sends a draft to every subscribed contact in its audience now. */
+            send: (id) => this.request('POST', pathTo('/campaigns', id, '/send')),
+            /** Copies a campaign into a new draft. */
+            duplicate: (id) => this.request('POST', pathTo('/campaigns', id, '/duplicate')),
+            remove: (id) => this.request('DELETE', pathTo('/campaigns', id)),
+        };
+        this.suppressions = {
+            /** Addresses that bounced, complained or were added by hand. Mailumi does not send to them. */
+            list: (q = {}) => this.request('GET', '/suppressions' + query(q)),
+            /** Allows sending to the address again. */
+            remove: (address) => this.request('DELETE', pathTo('/suppressions', address)),
         };
         this.audiences = {
             list: () => this.request('GET', '/audiences'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mailumi",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Official Mailumi SDK and CLI. Send transactional email and campaigns from your own domain, receive email by webhook, with your data stored in the EU.",
   "keywords": [
     "email",