mailumi 1.0.0 → 1.1.0

package/README.md

@@ -132,12 +132,18 @@ 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
@@ -215,7 +221,7 @@ Mailumi publishes [llms.txt](https://mailumi.com/llms.txt), [llms-full.txt](http
 ## 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.1.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';
@@ -189,6 +189,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 +302,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 {

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.1.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)

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.1.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';
@@ -189,6 +189,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 +302,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 {

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.1.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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mailumi",
-  "version": "1.0.0",
+  "version": "1.1.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",