@easybits.cloud/mailmask 0.9.0 → 0.9.1

package/README.md

@@ -156,6 +156,15 @@ const job = await mm.batch("formmy-user-42", {
 const st = await mm.batchStatus("formmy-user-42", job.batchId);
 // st.sent / failed / skippedSuppressed, then (for up to 7 days) delivered / bounced / complained / unsubscribed
 
+// Opens and clicks (opt-in per send/batch): `track: true` adds SES's open pixel and rewrites the html
+// links. Without it nothing is added. Unique counts + rates + top links come back in batchStatus, and
+// `email.opened` / `email.clicked` fire once per message (the first time). Opens are inflated by Apple
+// Mail Privacy Protection: decide by clicks.
+const tracked = await mm.batch("formmy-user-42", { from: "hola@laespiga.mx", subject: "Oct", html: "<a href=\"https://laespiga.mx/menu?utm_source=mail\">Menú</a>", recipients: ["ana@example.com"], track: true });
+const ts = await mm.batchStatus("formmy-user-42", tracked.batchId);
+// ts.opened / clicked (unique), ts.openRate / clickRate (0–1 over delivered, or sent while delivered is 0),
+// ts.topLinks: [{ url: "https://laespiga.mx/menu", clicks, uniqueClicks }] (utm_*, fbclid, gclid stripped)
+
 // Test mode: validates everything (signature, domain, suppression, quota) without sending or billing
 await mm.send("formmy-user-42", { from: "hola@laespiga.mx", to: "x@example.com", subject: "s", text: "t" }, { test: true });
 
@@ -208,6 +217,9 @@ export async function action({ request }: { request: Request }) {
     case "tenant.paused":
       // notify the customer
       break;
+    case "email.clicked":
+      // event.data.url, event.data.recipient, event.data.batchId, event.data.tags (first click only)
+      break;
   }
   return new Response("ok");
 }

package/dist/index.cjs

@@ -871,6 +871,8 @@ var PARTNER_WEBHOOK_EVENTS = [
   "email.delivered",
   "email.bounced",
   "email.complained",
+  "email.opened",
+  "email.clicked",
   "email.received",
   "contact.unsubscribed",
   "tenant.paused",
@@ -1306,7 +1308,10 @@ var MailMaskPartner = class {
     );
     return { ...data, idempotencyKey, replayed: meta.idempotentReplayed };
   }
-  /** Estado de un lote (`batchId` del resultado de `batch`): envíos y, después, entregas, rebotes, quejas y bajas. */
+  /**
+   * Estado de un lote (`batchId` del resultado de `batch`): envíos y, después, entregas, rebotes, quejas
+   * y bajas; con `track: true`, también aperturas, clics, tasas y `topLinks`.
+   */
   async batchStatus(externalId, batchId) {
     return (await this.request("GET", routePath(PARTNER_ROUTES.getBatch.path, { externalId, batchId }))).data;
   }

package/dist/index.js

@@ -774,6 +774,8 @@ var PARTNER_WEBHOOK_EVENTS = [
   "email.delivered",
   "email.bounced",
   "email.complained",
+  "email.opened",
+  "email.clicked",
   "email.received",
   "contact.unsubscribed",
   "tenant.paused",
@@ -1209,7 +1211,10 @@ var MailMaskPartner = class {
     );
     return { ...data, idempotencyKey, replayed: meta.idempotentReplayed };
   }
-  /** Estado de un lote (`batchId` del resultado de `batch`): envíos y, después, entregas, rebotes, quejas y bajas. */
+  /**
+   * Estado de un lote (`batchId` del resultado de `batch`): envíos y, después, entregas, rebotes, quejas
+   * y bajas; con `track: true`, también aperturas, clics, tasas y `topLinks`.
+   */
   async batchStatus(externalId, batchId) {
     return (await this.request("GET", routePath(PARTNER_ROUTES.getBatch.path, { externalId, batchId }))).data;
   }

package/dist/partner-contract.d.ts

@@ -336,6 +336,8 @@ export interface SendRequest {
     vars?: TemplateVars;
     /** Reintentar con la misma llave en 24 h devuelve la respuesta guardada sin volver a enviar. */
     idempotencyKey?: string;
+    /** Mide aperturas y clics (ver `track` en `BatchRequest`). Default `false`. */
+    track?: boolean;
 }
 /** `POST /tenants/:externalId/send` — 200. Con `Idempotent-Replayed: true` si fue repetición. */
 export interface SendResponse {
@@ -368,6 +370,21 @@ export interface BatchRequest {
     /** Default `broadcast` (lleva baja de un clic por destinatario). */
     stream?: MessageStream;
     idempotencyKey?: string;
+    /**
+     * Mide aperturas y clics: SES agrega un pixel invisible y reescribe cada liga del `html` para
+     * pasar por su redirector (el `text` no cambia). Llegan `email.opened`/`email.clicked` (la primera
+     * vez por correo) y suben `opened`, `clicked` y `topLinks` del `BatchStatus`. Default `false`: sin
+     * él el correo sale sin pixel y con las ligas intactas.
+     */
+    track?: boolean;
+}
+/** Una liga del lote con sus clics. `url` va sin `utm_*`, `fbclid` ni `gclid` (agrupa variantes). */
+export interface BatchTopLink {
+    url: string;
+    /** Clics totales (una persona que hace clic dos veces cuenta dos). */
+    clicks: number;
+    /** Correos distintos que hicieron clic en esta liga. */
+    uniqueClicks: number;
 }
 export type BatchState = "queued" | "processing" | "completed" | "failed";
 export interface BatchStatus {
@@ -387,6 +404,21 @@ export interface BatchStatus {
     bounced: number;
     complained: number;
     unsubscribed: number;
+    /** El lote se mandó con `track: true`. Sin él, los números de seguimiento se quedan en 0. */
+    track: boolean;
+    /**
+     * Correos del lote abiertos al menos una vez (únicos). Inflado: Apple Mail (Mail Privacy
+     * Protection) y algunos filtros abren el pixel solos. Para decidir, usa los clics.
+     */
+    opened: number;
+    /** Correos del lote con al menos un clic (únicos). Excluye la liga de baja. */
+    clicked: number;
+    /** `opened` / `delivered` (o / `sent` mientras `delivered` sea 0), de 0 a 1 con 4 decimales. */
+    openRate: number;
+    /** `clicked` sobre la misma base que `openRate`. */
+    clickRate: number;
+    /** Hasta 10 ligas con más clics, de más a menos. */
+    topLinks: BatchTopLink[];
     lastError: string | null;
     createdAt: string;
     completedAt: string | null;
@@ -559,6 +591,11 @@ export interface AutoTopup {
  */
 export interface SetAutoTopupRequest {
     amount: number | null;
+    /**
+     * Correo de la cuenta de MercadoPago con que se paga, si no es el del dueño en MailMask
+     * (MercadoPago rechaza el de su propia cuenta cobradora).
+     */
+    payerEmail?: string;
     returnUrl?: string;
 }
 /** Montos sugeridos para la recarga automática (unidades enteras). */
@@ -628,7 +665,7 @@ export interface RotateWebhookSecretResponse {
 export interface TestWebhookResponse {
     deliveryId: string;
 }
-export declare const PARTNER_WEBHOOK_EVENTS: readonly ["email.sent", "email.delivered", "email.bounced", "email.complained", "email.received", "contact.unsubscribed", "tenant.paused", "tenant.resumed", "domain.verified", "balance.low", "batch.throttled"];
+export declare const PARTNER_WEBHOOK_EVENTS: readonly ["email.sent", "email.delivered", "email.bounced", "email.complained", "email.opened", "email.clicked", "email.received", "contact.unsubscribed", "tenant.paused", "tenant.resumed", "domain.verified", "balance.low", "batch.throttled"];
 export type PartnerWebhookEvent = typeof PARTNER_WEBHOOK_EVENTS[number];
 /** Headers de cada entrega al webhook del partner (los mismos que los webhooks de dominio). */
 export declare const WEBHOOK_HEADERS: {
@@ -675,6 +712,24 @@ export interface PartnerEventData {
         recipient: string;
         feedbackType: string | null;
     };
+    /**
+     * Primera apertura de un correo enviado con `track: true` (una sola vez por correo). Inflado por
+     * Apple Mail Privacy Protection: decide por `email.clicked`.
+     */
+    "email.opened": EmailEventBase & {
+        recipient: string;
+        batchId: string | null;
+        openedAt: string;
+        userAgent: string | null;
+    };
+    /** Primer clic de un correo enviado con `track: true` (una sola vez por correo). `url` es la liga original. */
+    "email.clicked": EmailEventBase & {
+        recipient: string;
+        batchId: string | null;
+        url: string;
+        clickedAt: string;
+        userAgent: string | null;
+    };
     "email.received": {
         domain: string;
         from: string;

package/dist/partner.d.ts

@@ -237,7 +237,10 @@ export declare class MailMaskPartner {
         idempotencyKey: string;
         replayed: boolean;
     }>;
-    /** Estado de un lote (`batchId` del resultado de `batch`): envíos y, después, entregas, rebotes, quejas y bajas. */
+    /**
+     * Estado de un lote (`batchId` del resultado de `batch`): envíos y, después, entregas, rebotes, quejas
+     * y bajas; con `track: true`, también aperturas, clics, tasas y `topLinks`.
+     */
     batchStatus(externalId: string, batchId: string): Promise<BatchStatus>;
     /** Saldo prepagado: saldo, precios, última recarga y consumo del mes (centavos MXN). */
     balance(): Promise<BalanceResponse>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@easybits.cloud/mailmask",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "Official SDK for the MailMask email alias/forwarding API",
   "type": "module",
   "main": "./dist/index.cjs",