@mailiy/sdk 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 26LAB.IO, Christian Gudermann
+
+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,46 @@
-# Temporary Holding Version
+# @mailiy/sdk
 
-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.
+Typed client for the [Mailiy](https://mailiy.com/en/) REST API. No dependencies, runs in Node 18+, Deno, Bun and edge runtimes.
+
+```bash
+npm install @mailiy/sdk
+```
+
+## Usage
+
+Create an API key in the dashboard under API keys. Keep it on the server; it has access to your whole account (or to the websites its scope allows).
+
+```ts
+import { createMailiy, MailiyError } from "@mailiy/sdk";
+
+const mailiy = createMailiy({ apiKey: process.env.MAILIY_API_KEY });
+
+const site = await mailiy.createWebsite({ name: "example.com" });
+const { id } = await mailiy.createForm({
+  name: "Contact",
+  website_id: site.id,
+});
+const form = await mailiy.getForm(id);
+
+try {
+  const { submissions } = await mailiy.pageSubmissions(id, { limit: 50 });
+} catch (error) {
+  if (error instanceof MailiyError && error.code === "rate_limited") {
+    // 120 requests per minute per key
+  }
+}
+```
+
+The client talks to `https://mailiy.com`. Set `baseUrl` (or the `MAILIY_URL` environment variable) to use another instance, and `fetch` to pass your own fetch function.
+
+Failed requests throw a `MailiyError` with the HTTP `status` and the API's error `code`.
+
+All methods and fields are listed in the [API docs](https://mailiy.com/en/docs/) and the [OpenAPI spec](https://mailiy.com/openapi.json).
+
+## Forms in the browser
+
+To send a form from a website you only need the form's public access key, not this SDK. See [@mailiy/react](https://www.npmjs.com/package/@mailiy/react) or the [guides](https://mailiy.com/en/guides/).
+
+## License
+
+MIT

package/dist/mailiy.d.ts

@@ -0,0 +1,349 @@
+/**
+ * Mailiy SDK: a typed, dependency-free client for the Mailiy REST API.
+ *
+ *   import { createMailiy } from "@mailiy/sdk";
+ *   const mailiy = createMailiy({ apiKey: process.env.MAILIY_API_KEY });
+ *   const site = await mailiy.createWebsite({ name: "example.de" });
+ *   const { id } = await mailiy.createForm({ name: "Contact", website_id: site.id });
+ */
+type Retention = 0 | 7 | 30 | 90 | 180 | 365;
+type Captcha = "" | "altcha" | "hcaptcha" | "turnstile" | "recaptcha";
+type SpamFilter = "" | "basic" | "strict";
+export type EmailTemplate = "default" | "plain" | "minimal" | "modern" | "compact" | "dark" | "custom";
+export interface MailiyWebsite {
+    id: string;
+    name: string;
+    domains: string;
+    recipients: string[];
+    from_name: string;
+    retention_days: number;
+    captcha: Captcha;
+    /** The secret itself is never returned. */
+    captcha_secret_set: boolean;
+    created_at: number;
+    forms?: number;
+    /** Usage counters (delivered and blocked spam) since the counters exist. */
+    delivered?: number;
+    spam?: number;
+}
+export type MailiyWebsitePatch = Partial<{
+    domains: string;
+    from_name: string;
+    name: string;
+    recipients: string[];
+    retention_days: Retention;
+    captcha: Captcha;
+    /** Server-side key of hCaptcha, Turnstile or reCAPTCHA; "" clears it. */
+    captcha_secret: string;
+}>;
+export interface MailiyForm {
+    id: string;
+    website_id: string;
+    name: string;
+    website: string;
+    recipients: string[];
+    subject: string;
+    from_name: string;
+    redirect_url: string;
+    allowed_domains: string;
+    retention_days: number;
+    captcha: Captcha;
+    captcha_secret_set: boolean;
+    require_consent: number;
+    autoresponder_subject: string;
+    autoresponder_text: string;
+    email_template: EmailTemplate;
+    /** Used when email_template is "custom". */
+    email_html: string;
+    intro_text: string;
+    spam_filter: SpamFilter;
+    /** IPs and CIDR ranges, one per line. */
+    blocked_ips: string;
+    group_emails: number;
+    server_requires_key: number;
+    disabled: number;
+    /** Submissions are refused before this time (ms since epoch); null: no start. */
+    opens_at: number | null;
+    /** Submissions are refused from this time on (ms since epoch); null: no end. */
+    closes_at: number | null;
+    /** Delivered submissions after which the form answers form_full; 0: no limit. */
+    max_submissions: number;
+    /** Field names, one per line; a submission missing one gets missing_fields. */
+    required_fields: string;
+    created_at: number;
+    submissions?: number;
+    delivered?: number;
+}
+export interface MailiySubmission {
+    id: string;
+    form_id: string;
+    created_at: number;
+    consent_at: number | null;
+    data: [string, string][];
+    /** Uploaded files; each url downloads without login for one hour. */
+    files: {
+        id: string;
+        field: string;
+        name: string;
+        size: number;
+        type: string;
+        url: string;
+    }[];
+    spam: boolean;
+}
+export interface MailiySubmissionFilter {
+    /** next_cursor of the previous result: opens the next block of 1000 older submissions. */
+    cursor?: string;
+    form?: string;
+    page?: number;
+    q?: string;
+    status?: "delivered" | "spam";
+}
+export interface MailiySubmissionPage {
+    keys: string[];
+    /** Set when older submissions exist beyond this block of 1000. */
+    next_cursor: string | null;
+    page: number;
+    pages: number;
+    rows: (MailiySubmission & {
+        form_name: string;
+    })[];
+    total: number;
+}
+export interface MailiyStats {
+    range: "7d" | "30d" | "12m";
+    /** One point per day (YYYY-MM-DD) or month (YYYY-MM), oldest first, gaps filled with 0. */
+    points: {
+        date: string;
+        delivered: number;
+        spam: number;
+    }[];
+}
+/** Service health. backup only appears where the operator has set up backups. */
+export interface MailiyStatus {
+    status: "ok" | "degraded";
+    checked_at: number;
+    checks: {
+        database: boolean;
+        jobs: boolean;
+        mail: boolean;
+        backup?: boolean;
+    };
+}
+/** A stored file in a website, newest first. */
+export interface MailiyWebsiteFile {
+    id: string;
+    field: string;
+    name: string;
+    size: number;
+    type: string;
+    /** Downloads without login for one hour. */
+    url: string;
+    created_at: number;
+    form_id: string;
+    form_name: string;
+    submission_id: string;
+}
+export type MailiyIntegrationKind = "webhook" | "slack" | "discord" | "telegram";
+/** Sends every submission of a website, or of one form, to a webhook or chat. */
+export interface MailiyIntegration {
+    id: string;
+    website_id: string;
+    /** Null: every form of the website. */
+    form_id: string | null;
+    kind: MailiyIntegrationKind;
+    label: string;
+    /** Masked destination; the full URL or bot token is never returned. */
+    hint: string;
+    /** Webhooks only: HMAC key for the Mailiy-Signature header. */
+    secret: string | null;
+    disabled: boolean;
+    created_at: number;
+}
+export type MailiyIntegrationInput = {
+    form_id?: string | undefined;
+    label?: string | undefined;
+} & ({
+    kind: "webhook" | "slack" | "discord";
+    url: string;
+} | {
+    kind: "telegram";
+    bot_token: string;
+    chat_id: string;
+});
+/** One send attempt series; failed ones are retried up to 6 times over about 9 hours. */
+export interface MailiyDelivery {
+    id: string;
+    integration_id: string;
+    status: "failed" | "ok" | "pending";
+    attempts: number;
+    http_status: number | null;
+    /** Error code such as EBLOCKED, ETIMEDOUT or http_500; empty on success. */
+    error: string;
+    next_attempt_at: number;
+    created_at: number;
+    /** True while the payload is still stored (7 days). */
+    can_retry: boolean;
+}
+export interface MailiyRenderedEmail {
+    subject: string;
+    html: string;
+    text: string;
+}
+export type MailiyFormPatch = Partial<{
+    allowed_domains: string;
+    autoresponder_subject: string;
+    autoresponder_text: string;
+    blocked_ips: string;
+    closes_at: number | null;
+    disabled: boolean;
+    /** Placeholders: {fields}, {intro}, {form}, {field:name}. */
+    email_html: string;
+    email_template: EmailTemplate;
+    from_name: string;
+    group_emails: boolean;
+    intro_text: string;
+    max_submissions: number;
+    name: string;
+    opens_at: number | null;
+    recipients: string[];
+    redirect_url: string;
+    require_consent: boolean;
+    /** Field names, one per line. */
+    required_fields: string;
+    retention_days: Retention;
+    captcha: Captcha;
+    captcha_secret: string;
+    server_requires_key: boolean;
+    spam_filter: SpamFilter;
+    subject: string;
+    website: string;
+}>;
+export interface MailiyOptions {
+    /** Personal API key from Dashboard → Account → API keys (starts with mk_). */
+    apiKey?: string | undefined;
+    /** Defaults to MAILIY_URL, then https://mailiy.com. */
+    baseUrl?: string | undefined;
+    /** Custom fetch, e.g. for tests or proxies. */
+    fetch?: typeof fetch;
+}
+export interface MailiyCursorFilter {
+    cursor?: string | undefined;
+    /** 1 to 500, default 500. */
+    limit?: number | undefined;
+    spam?: boolean | undefined;
+}
+export declare class MailiyError extends Error {
+    name: string;
+    readonly code: string;
+    readonly status: number;
+    constructor(code: string, status: number);
+}
+export declare const DEFAULT_BASE_URL = "https://mailiy.com";
+export declare const createMailiy: (options?: MailiyOptions) => {
+    /** Without website_id the form goes into the account's only website. */
+    createForm: (input: {
+        name: string;
+        website?: string | undefined;
+        website_id?: string | undefined;
+    }) => Promise<{
+        id: string;
+        website_id: string;
+    }>;
+    /** Website-wide unless form_id is set. Webhook URLs must be https and public. */
+    createIntegration: (websiteId: string, input: MailiyIntegrationInput) => Promise<MailiyIntegration>;
+    createWebsite: (input: {
+        name: string;
+        domains?: string | undefined;
+    }) => Promise<{
+        id: string;
+    }>;
+    /** Deletes one uploaded file to free storage; the submission stays. */
+    deleteFile: (id: string) => Promise<{
+        ok: true;
+    }>;
+    deleteForm: (id: string) => Promise<{
+        ok: true;
+    }>;
+    deleteIntegration: (id: string) => Promise<{
+        ok: true;
+    }>;
+    deleteSubmission: (formId: string, submissionId: string) => Promise<{
+        ok: true;
+    }>;
+    /** Deletes the website with all its forms and stored submissions. */
+    deleteWebsite: (id: string) => Promise<{
+        ok: true;
+    }>;
+    /** Copies a form with all settings under a new access key. */
+    duplicateForm: (id: string, name?: string) => Promise<{
+        id: string;
+        name: string;
+    }>;
+    getForm: (id: string) => Promise<MailiyForm>;
+    /** Public service health, cached for 30 seconds. */
+    getStatus: () => Promise<MailiyStatus>;
+    getWebsite: (id: string) => Promise<MailiyWebsite>;
+    /** The newest 50 deliveries of an integration. */
+    listDeliveries: (id: string) => Promise<MailiyDelivery[]>;
+    listForms: (websiteId?: string) => Promise<MailiyForm[]>;
+    listIntegrations: (websiteId: string) => Promise<MailiyIntegration[]>;
+    /** Up to `limit` submissions (default and maximum 500). With spam: true it lists the spam tab (kept for 7 days). */
+    listSubmissions: (formId: string, filter?: MailiyCursorFilter) => Promise<MailiySubmission[]>;
+    /** Uploaded files of all forms in the website (up to 500). */
+    listWebsiteFiles: (id: string) => Promise<MailiyWebsiteFile[]>;
+    listWebsites: () => Promise<MailiyWebsite[]>;
+    /** Delivers a submission from the spam tab and moves it to the normal list. */
+    markNotSpam: (formId: string, submissionId: string) => Promise<{
+        ok: true;
+    }>;
+    pageSubmissions: (formId: string, filter?: MailiyCursorFilter) => Promise<{
+        next_cursor: string | null;
+        submissions: MailiySubmission[];
+    }>;
+    /** Renders the notification and auto-reply with sample data; patch fields override the saved ones. */
+    previewEmail: (id: string, patch?: MailiyFormPatch) => Promise<MailiyRenderedEmail & {
+        autoresponder: MailiyRenderedEmail | null;
+    }>;
+    /** Sends a failed delivery once more, as long as its payload is still stored. */
+    retryDelivery: (id: string) => Promise<MailiyDelivery>;
+    /** Replaces the access key; the old one stops working at once. Submissions move to the new id. */
+    rotateAccessKey: (id: string) => Promise<{
+        id: string;
+    }>;
+    /** Submissions of all forms in the account (or one website), 25 per page, newest first, in blocks of 1000 (see cursor). */
+    searchSubmissions: (filter?: MailiySubmissionFilter & {
+        website?: string;
+    }) => Promise<MailiySubmissionPage>;
+    /** Submissions of all forms in a website, 25 per page, newest first, in blocks of 1000 (see cursor). */
+    searchWebsiteSubmissions: (id: string, filter?: MailiySubmissionFilter) => Promise<MailiySubmissionPage>;
+    sendTest: (id: string) => Promise<{
+        ok: true;
+    }>;
+    /** Delivered and spam counts per day (7d, 30d) or month (12m), for the account or one website. */
+    stats: (range?: "7d" | "30d" | "12m", website?: string) => Promise<MailiyStats>;
+    /**
+     * Public endpoint: the access key is the form id. With apiKey set, the key is sent too, which
+     * forms with server_requires_key need and which skips the origin and captcha checks.
+     */
+    submit: (accessKey: string, fields: Record<string, string>) => Promise<{
+        success: boolean;
+        message: string;
+        body: {
+            data: Record<string, string>;
+            message: string;
+        };
+    }>;
+    /** Sends a sample submission and returns the logged delivery. */
+    testIntegration: (id: string) => Promise<MailiyDelivery>;
+    updateForm: (id: string, patch: MailiyFormPatch) => Promise<MailiyForm>;
+    updateIntegration: (id: string, patch: {
+        disabled?: boolean;
+        label?: string;
+    }) => Promise<MailiyIntegration>;
+    updateWebsite: (id: string, patch: MailiyWebsitePatch) => Promise<MailiyWebsite>;
+};
+export type Mailiy = ReturnType<typeof createMailiy>;
+/** The HTML snippet that sends a form to Mailiy. */
+export declare const formSnippet: (accessKey: string, baseUrl: string) => string;
+export {};

package/dist/mailiy.js

@@ -0,0 +1,131 @@
+/**
+ * Mailiy SDK: a typed, dependency-free client for the Mailiy REST API.
+ *
+ *   import { createMailiy } from "@mailiy/sdk";
+ *   const mailiy = createMailiy({ apiKey: process.env.MAILIY_API_KEY });
+ *   const site = await mailiy.createWebsite({ name: "example.de" });
+ *   const { id } = await mailiy.createForm({ name: "Contact", website_id: site.id });
+ */
+export class MailiyError extends Error {
+    name = "MailiyError";
+    code;
+    status;
+    constructor(code, status) {
+        super(`Mailiy API error ${status}: ${code}`);
+        this.code = code;
+        this.status = status;
+    }
+}
+const form = (id) => `/forms/${encodeURIComponent(id)}`;
+const integration = (id) => `/integrations/${encodeURIComponent(id)}`;
+const query = (params) => new URLSearchParams(Object.entries(params).flatMap(([key, value]) => value === undefined ? [] : [[key, String(value)]])).toString();
+const site = (id) => `/websites/${encodeURIComponent(id)}`;
+export const DEFAULT_BASE_URL = "https://mailiy.com";
+export const createMailiy = (options = {}) => {
+    // Browsers have no process object.
+    const envUrl = typeof process === "undefined" ? undefined : process.env.MAILIY_URL;
+    const baseUrl = (options.baseUrl ?? envUrl ?? DEFAULT_BASE_URL).replace(/\/$/u, "");
+    const doFetch = options.fetch ?? fetch;
+    const send = async (path, method = "GET", body) => {
+        const headers = { accept: "application/json" };
+        if (options.apiKey) {
+            headers.authorization = `Bearer ${options.apiKey}`;
+        }
+        if (body !== undefined) {
+            headers["content-type"] = "application/json";
+        }
+        const res = await doFetch(`${baseUrl}/api${path}`, {
+            body: body === undefined ? null : JSON.stringify(body),
+            headers,
+            method,
+        });
+        const json = (await res.json().catch(() => ({})));
+        if (!res.ok) {
+            throw new MailiyError(json.error ?? json.code ?? res.statusText, res.status);
+        }
+        return { headers: res.headers, json };
+    };
+    const call = async (path, method = "GET", body) => {
+        const { json } = await send(path, method, body);
+        return json;
+    };
+    /** One page of submissions, newest first; pass next_cursor back as cursor for the next one. */
+    const pageSubmissions = async (formId, filter = {}) => {
+        const params = query({
+            cursor: filter.cursor,
+            limit: filter.limit,
+            spam: filter.spam ? true : undefined,
+        });
+        const { headers, json } = await send(`${form(formId)}/submissions${params ? `?${params}` : ""}`);
+        return { next_cursor: headers.get("x-next-cursor"), submissions: json };
+    };
+    return {
+        /** Without website_id the form goes into the account's only website. */
+        createForm: (input) => call("/forms", "POST", input),
+        /** Website-wide unless form_id is set. Webhook URLs must be https and public. */
+        createIntegration: (websiteId, input) => call(`${site(websiteId)}/integrations`, "POST", input),
+        createWebsite: (input) => call("/websites", "POST", input),
+        /** Deletes one uploaded file to free storage; the submission stays. */
+        deleteFile: (id) => call(`/files/${encodeURIComponent(id)}`, "DELETE"),
+        deleteForm: (id) => call(form(id), "DELETE"),
+        deleteIntegration: (id) => call(integration(id), "DELETE"),
+        deleteSubmission: (formId, submissionId) => call(`${form(formId)}/submissions/${encodeURIComponent(submissionId)}`, "DELETE"),
+        /** Deletes the website with all its forms and stored submissions. */
+        deleteWebsite: (id) => call(site(id), "DELETE"),
+        /** Copies a form with all settings under a new access key. */
+        duplicateForm: (id, name) => call(`${form(id)}/duplicate`, "POST", name === undefined ? {} : { name }),
+        getForm: (id) => call(form(id)),
+        /** Public service health, cached for 30 seconds. */
+        getStatus: () => call("/status"),
+        getWebsite: (id) => call(site(id)),
+        /** The newest 50 deliveries of an integration. */
+        listDeliveries: (id) => call(`${integration(id)}/deliveries`),
+        listForms: (websiteId) => call(websiteId ? `/forms?website=${encodeURIComponent(websiteId)}` : "/forms"),
+        listIntegrations: (websiteId) => call(`${site(websiteId)}/integrations`),
+        /** Up to `limit` submissions (default and maximum 500). With spam: true it lists the spam tab (kept for 7 days). */
+        listSubmissions: async (formId, filter = {}) => {
+            const page = await pageSubmissions(formId, filter);
+            return page.submissions;
+        },
+        /** Uploaded files of all forms in the website (up to 500). */
+        listWebsiteFiles: (id) => call(`${site(id)}/files`),
+        listWebsites: () => call("/websites"),
+        /** Delivers a submission from the spam tab and moves it to the normal list. */
+        markNotSpam: (formId, submissionId) => call(`${form(formId)}/submissions/${encodeURIComponent(submissionId)}/not-spam`, "POST"),
+        pageSubmissions,
+        /** Renders the notification and auto-reply with sample data; patch fields override the saved ones. */
+        previewEmail: (id, patch = {}) => call(`${form(id)}/preview`, "POST", patch),
+        /** Sends a failed delivery once more, as long as its payload is still stored. */
+        retryDelivery: (id) => call(`/deliveries/${encodeURIComponent(id)}/retry`, "POST"),
+        /** Replaces the access key; the old one stops working at once. Submissions move to the new id. */
+        rotateAccessKey: (id) => call(`${form(id)}/rotate-key`, "POST"),
+        /** Submissions of all forms in the account (or one website), 25 per page, newest first, in blocks of 1000 (see cursor). */
+        searchSubmissions: (filter = {}) => call(`/submissions?${query(filter)}`),
+        /** Submissions of all forms in a website, 25 per page, newest first, in blocks of 1000 (see cursor). */
+        searchWebsiteSubmissions: (id, filter = {}) => call(`${site(id)}/submissions?${query(filter)}`),
+        sendTest: (id) => call(`${form(id)}/test`, "POST"),
+        /** Delivered and spam counts per day (7d, 30d) or month (12m), for the account or one website. */
+        stats: (range = "30d", website) => call(`/stats?${query({ range, website })}`),
+        /**
+         * Public endpoint: the access key is the form id. With apiKey set, the key is sent too, which
+         * forms with server_requires_key need and which skips the origin and captcha checks.
+         */
+        submit: (accessKey, fields) => call("/submit", "POST", {
+            ...fields,
+            access_key: accessKey,
+        }),
+        /** Sends a sample submission and returns the logged delivery. */
+        testIntegration: (id) => call(`${integration(id)}/test`, "POST"),
+        updateForm: (id, patch) => call(form(id), "PATCH", patch),
+        updateIntegration: (id, patch) => call(integration(id), "PATCH", patch),
+        updateWebsite: (id, patch) => call(site(id), "PATCH", patch),
+    };
+};
+/** The HTML snippet that sends a form to Mailiy. */
+export const formSnippet = (accessKey, baseUrl) => `<form action="${baseUrl}/api/submit" method="POST">
+  <input type="hidden" name="access_key" value="${accessKey}">
+  <input type="email" name="email" required>
+  <textarea name="message" required></textarea>
+  <input type="checkbox" name="botcheck" style="display:none">
+  <button>Send</button>
+</form>`;

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "@mailiy/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Typed, dependency-free client for the Mailiy REST API.",
+  "keywords": [
+    "api-client",
+    "contact-form",
+    "form-to-email",
+    "forms",
+    "mailiy"
+  ],
+  "homepage": "https://mailiy.com/en/docs/",
+  "license": "MIT",
+  "author": "26LAB.IO, Christian Gudermann",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/mailiy.d.ts",
+      "default": "./dist/mailiy.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}