mailumi 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mailumi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,225 @@
-# Temporary Holding Version
+# mailumi
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The official Node.js SDK and CLI for [Mailumi](https://mailumi.com), the email API for sending transactional email and campaigns from your own domain and receiving email as signed webhooks. Email content and account data are stored in the European Union, and email is sent through Amazon SES in Ireland.
+
+- Typed, zero dependencies, ESM and CommonJS
+- Runs on Node.js 18+, Bun, Deno, Cloudflare Workers, Vercel and any runtime with `fetch`
+- 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
+
+## Install
+
+```sh
+npm install mailumi
+```
+
+Create an API key in [Dashboard → API keys](https://mailumi.com/dashboard/api-keys) and verify your domain in [Dashboard → Domains](https://mailumi.com/dashboard/domains). On Cloudflare, Mailumi adds the DNS records for you.
+
+```sh
+MAILUMI_API_KEY=mlu_live_...
+```
+
+## Send an email
+
+```ts
+import { Mailumi } from 'mailumi';
+
+const mailumi = new Mailumi(process.env.MAILUMI_API_KEY);
+
+const { data, error } = await mailumi.emails.send({
+  from: 'Acme <hello@yourdomain.com>',
+  to: 'jane@example.com',
+  subject: 'Welcome to Acme',
+  html: '<p>Thanks for signing up.</p>',
+});
+
+if (error) {
+  console.error(error.code, error.message);
+} else {
+  console.log('Queued', data.id);
+}
+```
+
+With no argument, `new Mailumi()` reads `MAILUMI_API_KEY`. CommonJS works too: `const { Mailumi } = require('mailumi')`.
+
+Only call Mailumi from server-side code. Never put your API key in browser or mobile code.
+
+## Switching from Resend
+
+The method names and the `{ data, error }` result match the Resend SDK, so most code only needs a new import and API key:
+
+```diff
+- import { Resend } from 'resend';
+- const resend = new Resend(process.env.RESEND_API_KEY);
++ import { Mailumi } from 'mailumi';
++ const resend = new Mailumi(process.env.MAILUMI_API_KEY);
+
+  await resend.emails.send({ from, to, subject, html });
+```
+
+Both `replyTo` and `reply_to` style options are accepted. Verify your domain in Mailumi before sending; the `from` address must use it.
+
+## More ways to send
+
+```ts
+import { readFile } from 'node:fs/promises';
+
+// Several recipients, cc, bcc and reply-to. Each recipient counts as one email.
+await mailumi.emails.send({
+  from: 'Acme <billing@yourdomain.com>',
+  to: ['jane@example.com', 'sam@example.com'],
+  cc: 'finance@example.com',
+  replyTo: 'support@yourdomain.com',
+  subject: 'Your invoice',
+  text: 'Your invoice is attached.',
+  attachments: [{ filename: 'invoice.pdf', content: await readFile('invoice.pdf') }],
+  tags: [{ name: 'type', value: 'invoice' }],
+});
+
+// Schedule up to 30 days ahead: a Date, an ISO 8601 string, or "in 30 minutes", "in 2 hours", "in 3 days".
+const { data } = await mailumi.emails.send({ from, to, subject, html, scheduledAt: 'in 3 days' });
+await mailumi.emails.update({ id: data.id, scheduledAt: new Date('2030-01-01T09:00:00Z') });
+await mailumi.emails.cancel(data.id);
+
+// A template from Dashboard → Templates, with variables.
+await mailumi.emails.send({ from, to, templateId: 'tpl_...', variables: { name: 'Jane' } });
+
+// Up to 100 emails in one request. If one is invalid, none are sent.
+await mailumi.batch.send([
+  { from, to: 'jane@example.com', subject: 'Hi Jane', text: '...' },
+  { from, to: 'sam@example.com', subject: 'Hi Sam', text: '...' },
+]);
+```
+
+Attachment `content` can be a base64 string or bytes (`Buffer`, `Uint8Array`, `ArrayBuffer`). Show an image inline with `contentId: 'logo'` and `<img src="cid:logo">`.
+
+### Idempotency
+
+Every send gets a random `Idempotency-Key`, reused on automatic retries. Pass your own to make a send safe to repeat across restarts or job retries:
+
+```ts
+await mailumi.emails.send(email, { idempotencyKey: `order-confirmation/${order.id}` });
+```
+
+Mailumi returns the original email for 24 hours. Using the same key for a different email returns a `conflict` error.
+
+## Delivery status and received email
+
+```ts
+const { data: email } = await mailumi.emails.get(id);
+email.status;      // queued, sent, delivered, bounced, ...
+email.recipients;  // status per recipient
+email.events;      // delivered, opened, clicked, bounced, complained, ...
+
+const { data: page } = await mailumi.emails.list({ direction: 'inbound' });
+const { data: bytes } = await mailumi.emails.attachment({ id, index: 0 });
+```
+
+## 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`.
+
+```ts
+import { verifyWebhook } from 'mailumi';
+
+export async function POST(request: Request) {
+  const { data: event, error } = await verifyWebhook({
+    payload: await request.text(), // the raw body, before JSON parsing
+    headers: request.headers,
+  });
+  if (error) return new Response(error.message, { status: 401 });
+
+  if (event.type === 'email.received') {
+    // event.data has from, to, subject, text, html and attachments
+  }
+  return new Response('OK');
+}
+```
+
+`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
+
+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.
+
+```ts
+const { data: audience } = await mailumi.audiences.create({ name: 'Newsletter' });
+
+await mailumi.contacts.create({ audienceId: audience.id, email: 'jane@example.com', firstName: 'Jane' });
+await mailumi.contacts.import({ audienceId: audience.id, contacts: [{ email: 'sam@example.com' }, { email: 'lee@example.com' }] }); // up to 1,000 per call
+await mailumi.contacts.update({ audienceId: audience.id, email: 'jane@example.com', unsubscribed: true });
+
+const { data } = await mailumi.contacts.list({ audienceId: audience.id, search: 'example.com' });
+```
+
+Unsubscribing applies to the address in every audience of the workspace, and adding or importing a contact never resubscribes it.
+
+## Errors
+
+```ts
+const { error } = await mailumi.emails.send(email);
+if (error) {
+  error.code;       // 'invalid_request', 'unauthorized', 'plan_limit_reached', 'rate_limited', ...
+  error.message;    // a readable explanation of what to fix
+  error.statusCode; // the HTTP status, or null for network errors
+}
+```
+
+| Code | Meaning |
+| --- | --- |
+| `invalid_request` | A field is missing or invalid; the message says which. |
+| `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. |
+| `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. |
+| `network_error` | Mailumi could not be reached or did not answer in time. |
+
+## Options
+
+```ts
+new Mailumi(apiKey, {
+  baseUrl: 'https://mailumi.com/api/v1', // or MAILUMI_BASE_URL
+  maxRetries: 2,   // retries for 429, 5xx and network errors
+  timeout: 30_000, // milliseconds per attempt
+  fetch,           // a custom fetch implementation
+});
+```
+
+## CLI
+
+```sh
+export MAILUMI_API_KEY=mlu_live_...
+
+npx mailumi send --from "Acme <hello@yourdomain.com>" --to jane@example.com \
+  --subject "Hello" --text "Sent from the terminal" --attach ./report.pdf
+
+npx mailumi emails list
+npx mailumi emails get <id>
+npx mailumi emails cancel <id>
+npx mailumi domains list
+npx mailumi audiences list
+npx mailumi contacts add <audience_id> jane@example.com --first-name Jane
+```
+
+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).
+
+## Links
+
+- [Documentation](https://mailumi.com/docs)
+- [Pricing](https://mailumi.com/pricing): the free plan includes 3,000 emails a month
+- [Support](https://mailumi.com/contact)
+
+## Versioning
+
+This package follows semantic versioning, as does the API: there are no breaking changes in v1. A breaking change only comes with a new major version, announced by email 6 months in advance, and v1 keeps working for at least 12 months after that.
+
+MIT License

package/dist/cjs/index.d.ts

@@ -0,0 +1,306 @@
+/**
+ * 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 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';
+    code: ErrorCode | (string & {});
+    message: string;
+    statusCode: number | null;
+}
+export type Result<T> = {
+    data: T;
+    error: null;
+} | {
+    data: null;
+    error: MailumiError;
+};
+export interface MailumiOptions {
+    /** Defaults to `https://mailumi.com/api/v1`. */
+    baseUrl?: string;
+    /** Retries for 429, 5xx and network errors. Sends reuse one Idempotency-Key, so a retry never sends twice. Other POSTs retry only on 429. Default 2. */
+    maxRetries?: number;
+    /** Milliseconds per attempt. Default 30000. */
+    timeout?: number;
+    /** A custom fetch implementation. */
+    fetch?: typeof fetch;
+}
+export interface RequestOptions {
+    idempotencyKey?: string;
+}
+export type Address = string;
+export interface Attachment {
+    filename: string;
+    /** Base64 string, or raw bytes (Uint8Array, Buffer, ArrayBuffer), which are encoded for you. */
+    content: string | Uint8Array | ArrayBuffer;
+    contentType?: string;
+    /** Show the file inline in HTML with `<img src="cid:…">`. */
+    contentId?: string;
+}
+export interface Tag {
+    name: string;
+    value: string;
+}
+export interface SendEmailOptions {
+    from: Address;
+    to: Address | Address[];
+    cc?: Address | Address[];
+    bcc?: Address | Address[];
+    replyTo?: Address | Address[];
+    subject?: string;
+    html?: string;
+    text?: string;
+    attachments?: Attachment[];
+    headers?: Record<string, string>;
+    tags?: Tag[];
+    /** Up to 30 days ahead: a Date, an ISO 8601 string, or "in 30 minutes", "in 2 hours", "in 3 days". */
+    scheduledAt?: Date | string;
+    /** Send a template from Dashboard → Templates instead of subject and html. */
+    templateId?: string;
+    variables?: Record<string, string>;
+}
+export interface Email {
+    id: string;
+    object: 'email';
+    domain_id?: string;
+    direction: 'outbound' | 'inbound';
+    from: string;
+    to: string[];
+    subject: string;
+    status: string;
+    last_event?: string;
+    scheduled_at: string | null;
+    tags?: Record<string, string>;
+    error: string | null;
+    created_at: string;
+}
+export interface EmailDetail extends Email {
+    cc?: string[];
+    bcc?: string[];
+    reply_to?: string[];
+    text?: string;
+    html?: string;
+    headers?: Record<string, string>;
+    content_deleted?: boolean;
+    recipients?: {
+        recipient: string;
+        kind: 'to' | 'cc' | 'bcc';
+        status: string;
+    }[];
+    events?: {
+        type: string;
+        recipient: string | null;
+        created_at: string;
+        [key: string]: unknown;
+    }[];
+    attachments?: {
+        id: string;
+        filename: string;
+        content_type: string;
+        content_id: string | null;
+        size: number;
+        download_url: string;
+    }[];
+}
+export interface EmailList {
+    data: Email[];
+    next_cursor: string | null;
+}
+export interface DnsRecord {
+    purpose: 'ownership' | 'dkim' | 'mail_from' | 'dmarc' | 'receiving';
+    required: boolean;
+    type: 'TXT' | 'CNAME' | 'MX';
+    name: string;
+    value: string;
+    priority?: number;
+    verified: boolean;
+}
+export interface Domain {
+    id: string;
+    name: string;
+    ownershipVerified?: boolean;
+    sendingEnabled?: boolean;
+    receivingEnabled?: boolean;
+    openTracking?: boolean;
+    clickTracking?: boolean;
+    sendingStatus: string;
+    receivingStatus?: string;
+    lastChecked?: number | null;
+    createdAt?: number;
+    records: DnsRecord[];
+}
+export interface Audience {
+    object: 'audience';
+    id: string;
+    name: string;
+    contacts: number;
+    subscribed: number;
+    created_at: string;
+}
+export interface Contact {
+    object: 'contact';
+    id: string;
+    audience_id: string;
+    email: string;
+    first_name: string;
+    last_name: string;
+    unsubscribed: boolean;
+    unsubscribed_at: string | null;
+    created_at: string;
+    updated_at: string;
+}
+export interface NewContact {
+    email: string;
+    firstName?: string;
+    lastName?: string;
+    unsubscribed?: boolean;
+}
+export interface ContactImport {
+    object: 'import';
+    audience_id: string;
+    added: number;
+    updated: number;
+    invalid: {
+        index: number;
+        email: string;
+        error: string;
+    }[];
+}
+export interface Deleted {
+    object: string;
+    id: string;
+    deleted: true;
+}
+type ContactRef = {
+    audienceId: string;
+} & ({
+    id: string;
+    email?: never;
+} | {
+    email: string;
+    id?: never;
+});
+export type WebhookEventType = 'email.sent' | 'email.delivered' | 'email.delivery_delayed' | 'email.bounced' | 'email.complained' | 'email.opened' | 'email.clicked' | 'email.failed' | 'email.unsubscribed' | 'email.received' | 'webhook.test';
+export interface WebhookEvent<T = Record<string, any>> {
+    id: string;
+    type: WebhookEventType | (string & {});
+    created_at: string;
+    data: T;
+}
+export interface VerifyWebhookOptions {
+    /** The raw request body exactly as received, before any JSON parsing. */
+    payload: string | Uint8Array;
+    /** A Headers object, Node's `req.headers`, or `{ id, timestamp, signature }`. */
+    headers: Headers | Record<string, string | string[] | undefined>;
+    /** The endpoint's `whsec_…` secret. Defaults to the MAILUMI_WEBHOOK_SECRET environment variable. */
+    secret?: string;
+    /** How many seconds the timestamp may differ from now. Default 300. */
+    tolerance?: number;
+}
+/**
+ * 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>>>;
+/** 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 {
+    readonly emails: {
+        /** Sends one email. Each recipient counts as one email toward your plan. */
+        send: (email: SendEmailOptions, o?: RequestOptions) => Promise<Result<Email>>;
+        /** Lists sent and received email, newest first, 50 per page. */
+        list: (q?: {
+            direction?: "outbound" | "inbound";
+            before?: string;
+        }) => Promise<Result<EmailList>>;
+        /** Returns the content, per-recipient status, events and attachment links. */
+        get: (id: string) => Promise<Result<EmailDetail>>;
+        /** Changes the send time of a scheduled email. */
+        update: ({ id, scheduledAt }: {
+            id: string;
+            scheduledAt: Date | string;
+        }) => Promise<Result<Email>>;
+        /** Cancels a scheduled email and returns it to your plan allowance. */
+        cancel: (id: string) => Promise<Result<{
+            object: "email";
+            id: string;
+            status: "canceled";
+        }>>;
+        /** Downloads one attachment of a sent or received email as bytes. */
+        attachment: ({ id, index }: {
+            id: string;
+            index: number | string;
+        }) => Promise<Result<Uint8Array<ArrayBufferLike>>>;
+    };
+    readonly batch: {
+        /** Sends up to 100 emails. If one is invalid, none are sent. */
+        send: (emails: SendEmailOptions[], o?: RequestOptions) => Promise<Result<{
+            data: {
+                id: string;
+            }[];
+        }>>;
+    };
+    readonly domains: {
+        /** Lists your domains, their DNS records and whether each is verified. */
+        list: () => Promise<Result<{
+            data: Domain[];
+        }>>;
+    };
+    readonly audiences: {
+        list: () => Promise<Result<{
+            data: Audience[];
+        }>>;
+        create: ({ name }: {
+            name: string;
+        }) => Promise<Result<Audience>>;
+        get: (id: string) => Promise<Result<Audience>>;
+        update: ({ id, name }: {
+            id: string;
+            name: string;
+        }) => Promise<Result<Audience>>;
+        /** Deletes the audience and its contacts. */
+        remove: (id: string) => Promise<Result<Deleted>>;
+    };
+    readonly contacts: {
+        /** Adds one contact, or updates its name if it exists. Importing never resubscribes anyone. */
+        create: ({ audienceId, ...contact }: NewContact & {
+            audienceId: string;
+        }) => Promise<Result<Contact>>;
+        /** Imports up to 1,000 contacts in one request. */
+        import: ({ audienceId, contacts }: {
+            audienceId: string;
+            contacts: NewContact[];
+        }) => Promise<Result<ContactImport>>;
+        /** Lists contacts sorted by email, 100 per page. */
+        list: ({ audienceId, after, search }: {
+            audienceId: string;
+            after?: string;
+            search?: string;
+        }) => Promise<Result<{
+            data: Contact[];
+            next_cursor: string | null;
+        }>>;
+        get: (ref: ContactRef) => Promise<Result<Contact>>;
+        /** Unsubscribing applies to the address in every audience of the workspace. */
+        update: ({ firstName, lastName, unsubscribed, ...ref }: ContactRef & {
+            firstName?: string;
+            lastName?: string;
+            unsubscribed?: boolean;
+        }) => 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;
+    };
+    private readonly key;
+    private readonly baseUrl;
+    private readonly maxRetries;
+    private readonly timeout;
+    private readonly fetcher;
+    constructor(apiKey?: string, options?: MailumiOptions);
+    private request;
+}
+export default Mailumi;