@easybits.cloud/mailmask 0.3.1 → 0.3.3

package/README.md

@@ -36,8 +36,20 @@ await mm.send.send(domainId, {
 
 // List aliases for a domain
 const aliases = await mm.aliases.list(domainId);
+
+// Add a domain — returns the DNS records to configure (MX, TXT, DKIM, SPF)
+const { domain, dnsRecords } = await mm.domains.create("yourdomain.com");
+
+// An alias with an IMAP mailbox (activated domain): password is returned once
+const inbox = await mm.aliases.create(domainId, { alias: "sales", mailbox: true });
+console.log(inbox.buzon?.password, inbox.buzon?.imap);
 ```
 
+## MCP
+
+The same actions are available to AI agents at `https://www.mailmask.studio/mcp`
+(Streamable HTTP, `Authorization: Bearer mk_...`). See https://www.mailmask.studio/docs#mcp.
+
 ## More
 
 ```ts
@@ -53,7 +65,7 @@ await mm.send.send(domainId, {
 await mm.suppressions.list(domainId);
 await mm.suppressions.remove(domainId, "fixed@example.com");
 
-// Webhooks (Developer plan) — secret is shown once
+// Webhooks (activated domain) — secret is shown once
 const wh = await mm.webhooks.create(domainId, { url: "https://app.example.com/hooks/mailmask", events: ["email.received", "email.delivered", "email.bounced"] });
 
 // On your server: verify the signature with the raw body

package/dist/index.cjs

@@ -93,7 +93,15 @@ var AliasesResource = class {
     return this.req(`/api/domains/${domainId}/alias`);
   }
   create(domainId, input) {
-    return this.req(`/api/domains/${domainId}/alias`, { method: "POST", body: JSON.stringify(input) });
+    return this.req(`/api/domains/${domainId}/alias`, { method: "POST", body: JSON.stringify({ ...input, destinations: input.destinations ?? [] }) });
+  }
+  /** Crea un buzón IMAP para una máscara existente. La contraseña sólo se devuelve aquí. */
+  createMailbox(domainId, alias) {
+    return this.req(`/api/domains/${domainId}/alias/${alias}/mailbox`, { method: "POST" });
+  }
+  /** Borra el buzón Y SU CORREO. La máscara debe conservar al menos un destino. */
+  deleteMailbox(domainId, alias) {
+    return this.req(`/api/domains/${domainId}/alias/${alias}/mailbox`, { method: "DELETE" });
   }
   update(domainId, alias, input) {
     return this.req(`/api/domains/${domainId}/alias/${alias}`, { method: "PUT", body: JSON.stringify(input) });

package/dist/index.d.cts

@@ -20,6 +20,24 @@ interface Domain {
     /** Sólo en `domains.list`: tope de reenvíos por hora del plan. */
     forwardPerHour?: number;
 }
+interface DnsRecord {
+    type: "MX" | "TXT" | "CNAME";
+    name: string;
+    value: string;
+    priority?: number;
+}
+/** Respuesta de `domains.create`: el dominio y los registros DNS que hay que poner. */
+interface DomainCreated {
+    domain: Domain;
+    /** true si es el 2.º dominio sin activar: se guarda pero no reenvía hasta activarlo ($99/mes). */
+    requiereActivacion: boolean;
+    dnsRecords: {
+        mx: DnsRecord;
+        verification: DnsRecord;
+        dkim: DnsRecord[];
+        spf: DnsRecord;
+    };
+}
 /** Respuesta de `domains.verify`. */
 interface DomainVerification {
     domain: string;
@@ -38,11 +56,37 @@ interface Alias {
     lastFrom?: string | null;
     lastAt?: string | null;
     createdAt: string;
+    /** true si la máscara guarda el correo en un buzón IMAP. */
+    mailboxEnabled?: boolean;
+}
+/** Credenciales de un buzón IMAP recién creado. La contraseña se muestra una sola vez. */
+interface MailboxCreated {
+    email: string;
+    password: string;
+    quotaBytes: number;
+    imap: {
+        host: string;
+        port: number;
+        security: string;
+    };
+    smtp: {
+        host: string;
+        port: number;
+        security: string;
+    };
+}
+/** `aliases.create`: el alias, y si pediste buzón, sus credenciales o por qué no se creó. */
+interface AliasCreated extends Alias {
+    buzon?: MailboxCreated | null;
+    errorBuzon?: string | null;
 }
 interface CreateAliasInput {
     /** Parte local, sin el dominio: "hola" para hola@tudominio.com. `*` para catch-all. */
     alias: string;
-    destinations: string[];
+    /** Adónde reenviar. Puede ir vacío sólo si `mailbox` es true. */
+    destinations?: string[];
+    /** Crear también un buzón IMAP (requiere dominio activado). */
+    mailbox?: boolean;
 }
 interface UpdateAliasInput {
     enabled?: boolean;
@@ -91,10 +135,13 @@ interface EmailLog {
     from: string;
     to: string;
     subject: string;
-    status: string;
+    /** Entrantes: forwarded, discarded, failed, rule_matched. Salientes: sent → delivered | bounced | complained. */
+    status: "forwarded" | "discarded" | "failed" | "rule_matched" | "sent" | "delivered" | "bounced" | "complained";
     forwardedTo: string;
     sizeBytes: number;
     error?: string;
+    /** Id interno de SES; cruza el log con los eventos de entrega. Sólo en salientes. */
+    sesMessageId?: string;
 }
 interface SendEmailInput {
     to: string;
@@ -278,9 +325,7 @@ declare class DomainsResource {
     constructor(req: Req);
     list(): Promise<Domain[]>;
     get(id: string): Promise<Domain>;
-    create(domain: string): Promise<{
-        domain: Domain;
-    }>;
+    create(domain: string): Promise<DomainCreated>;
     delete(id: string): Promise<{
         ok: boolean;
     }>;
@@ -291,7 +336,13 @@ declare class AliasesResource {
     private req;
     constructor(req: Req);
     list(domainId: string): Promise<Alias[]>;
-    create(domainId: string, input: CreateAliasInput): Promise<Alias>;
+    create(domainId: string, input: CreateAliasInput): Promise<AliasCreated>;
+    /** Crea un buzón IMAP para una máscara existente. La contraseña sólo se devuelve aquí. */
+    createMailbox(domainId: string, alias: string): Promise<MailboxCreated>;
+    /** Borra el buzón Y SU CORREO. La máscara debe conservar al menos un destino. */
+    deleteMailbox(domainId: string, alias: string): Promise<{
+        ok: boolean;
+    }>;
     update(domainId: string, alias: string, input: UpdateAliasInput): Promise<Alias>;
     delete(domainId: string, alias: string): Promise<{
         ok: boolean;
@@ -321,6 +372,7 @@ declare class SendResource {
     send(domainId: string, input: SendEmailInput, opts?: SendOptions): Promise<{
         ok: boolean;
         messageId: string;
+        sesMessageId: string;
     }>;
     bulkSend(domainId: string, input: BulkSendInput): Promise<BulkJobCreated>;
     bulkStatus(domainId: string, jobId: string): Promise<BulkJob>;
@@ -390,4 +442,4 @@ interface WebhookSignatureHeaders {
  */
 declare function verifyWebhookSignature(secret: string, headers: WebhookSignatureHeaders, rawBody: string, toleranceMs?: number): Promise<boolean>;
 
-export { type Alias, type ApiKey, type AttachmentRef, type BulkJob, type BulkJobCreated, type BulkSendInput, type CreateAliasInput, type CreateRuleInput, type CreateWebhookInput, type Domain, type DomainVerification, type EmailLog, MailMask, type MailMaskConfig, MailMaskError, type Rule, type RuleAction, type RuleField, type RuleMatch, type SendEmailInput, type SendOptions, type SmtpCredential, type SmtpCredentialCreated, type Suppression, type UpdateAliasInput, type UpdateRuleInput, type UpdateWebhookInput, type UploadAttachmentInput, type UploadedAttachment, type Webhook, type WebhookCreated, type WebhookDelivery, type WebhookEvent, type WebhookPayload, type WebhookSignatureHeaders, verifyWebhookSignature };
+export { type Alias, type AliasCreated, type ApiKey, type AttachmentRef, type BulkJob, type BulkJobCreated, type BulkSendInput, type CreateAliasInput, type CreateRuleInput, type CreateWebhookInput, type DnsRecord, type Domain, type DomainCreated, type DomainVerification, type EmailLog, MailMask, type MailMaskConfig, MailMaskError, type MailboxCreated, type Rule, type RuleAction, type RuleField, type RuleMatch, type SendEmailInput, type SendOptions, type SmtpCredential, type SmtpCredentialCreated, type Suppression, type UpdateAliasInput, type UpdateRuleInput, type UpdateWebhookInput, type UploadAttachmentInput, type UploadedAttachment, type Webhook, type WebhookCreated, type WebhookDelivery, type WebhookEvent, type WebhookPayload, type WebhookSignatureHeaders, verifyWebhookSignature };

package/dist/index.d.ts

@@ -20,6 +20,24 @@ interface Domain {
     /** Sólo en `domains.list`: tope de reenvíos por hora del plan. */
     forwardPerHour?: number;
 }
+interface DnsRecord {
+    type: "MX" | "TXT" | "CNAME";
+    name: string;
+    value: string;
+    priority?: number;
+}
+/** Respuesta de `domains.create`: el dominio y los registros DNS que hay que poner. */
+interface DomainCreated {
+    domain: Domain;
+    /** true si es el 2.º dominio sin activar: se guarda pero no reenvía hasta activarlo ($99/mes). */
+    requiereActivacion: boolean;
+    dnsRecords: {
+        mx: DnsRecord;
+        verification: DnsRecord;
+        dkim: DnsRecord[];
+        spf: DnsRecord;
+    };
+}
 /** Respuesta de `domains.verify`. */
 interface DomainVerification {
     domain: string;
@@ -38,11 +56,37 @@ interface Alias {
     lastFrom?: string | null;
     lastAt?: string | null;
     createdAt: string;
+    /** true si la máscara guarda el correo en un buzón IMAP. */
+    mailboxEnabled?: boolean;
+}
+/** Credenciales de un buzón IMAP recién creado. La contraseña se muestra una sola vez. */
+interface MailboxCreated {
+    email: string;
+    password: string;
+    quotaBytes: number;
+    imap: {
+        host: string;
+        port: number;
+        security: string;
+    };
+    smtp: {
+        host: string;
+        port: number;
+        security: string;
+    };
+}
+/** `aliases.create`: el alias, y si pediste buzón, sus credenciales o por qué no se creó. */
+interface AliasCreated extends Alias {
+    buzon?: MailboxCreated | null;
+    errorBuzon?: string | null;
 }
 interface CreateAliasInput {
     /** Parte local, sin el dominio: "hola" para hola@tudominio.com. `*` para catch-all. */
     alias: string;
-    destinations: string[];
+    /** Adónde reenviar. Puede ir vacío sólo si `mailbox` es true. */
+    destinations?: string[];
+    /** Crear también un buzón IMAP (requiere dominio activado). */
+    mailbox?: boolean;
 }
 interface UpdateAliasInput {
     enabled?: boolean;
@@ -91,10 +135,13 @@ interface EmailLog {
     from: string;
     to: string;
     subject: string;
-    status: string;
+    /** Entrantes: forwarded, discarded, failed, rule_matched. Salientes: sent → delivered | bounced | complained. */
+    status: "forwarded" | "discarded" | "failed" | "rule_matched" | "sent" | "delivered" | "bounced" | "complained";
     forwardedTo: string;
     sizeBytes: number;
     error?: string;
+    /** Id interno de SES; cruza el log con los eventos de entrega. Sólo en salientes. */
+    sesMessageId?: string;
 }
 interface SendEmailInput {
     to: string;
@@ -278,9 +325,7 @@ declare class DomainsResource {
     constructor(req: Req);
     list(): Promise<Domain[]>;
     get(id: string): Promise<Domain>;
-    create(domain: string): Promise<{
-        domain: Domain;
-    }>;
+    create(domain: string): Promise<DomainCreated>;
     delete(id: string): Promise<{
         ok: boolean;
     }>;
@@ -291,7 +336,13 @@ declare class AliasesResource {
     private req;
     constructor(req: Req);
     list(domainId: string): Promise<Alias[]>;
-    create(domainId: string, input: CreateAliasInput): Promise<Alias>;
+    create(domainId: string, input: CreateAliasInput): Promise<AliasCreated>;
+    /** Crea un buzón IMAP para una máscara existente. La contraseña sólo se devuelve aquí. */
+    createMailbox(domainId: string, alias: string): Promise<MailboxCreated>;
+    /** Borra el buzón Y SU CORREO. La máscara debe conservar al menos un destino. */
+    deleteMailbox(domainId: string, alias: string): Promise<{
+        ok: boolean;
+    }>;
     update(domainId: string, alias: string, input: UpdateAliasInput): Promise<Alias>;
     delete(domainId: string, alias: string): Promise<{
         ok: boolean;
@@ -321,6 +372,7 @@ declare class SendResource {
     send(domainId: string, input: SendEmailInput, opts?: SendOptions): Promise<{
         ok: boolean;
         messageId: string;
+        sesMessageId: string;
     }>;
     bulkSend(domainId: string, input: BulkSendInput): Promise<BulkJobCreated>;
     bulkStatus(domainId: string, jobId: string): Promise<BulkJob>;
@@ -390,4 +442,4 @@ interface WebhookSignatureHeaders {
  */
 declare function verifyWebhookSignature(secret: string, headers: WebhookSignatureHeaders, rawBody: string, toleranceMs?: number): Promise<boolean>;
 
-export { type Alias, type ApiKey, type AttachmentRef, type BulkJob, type BulkJobCreated, type BulkSendInput, type CreateAliasInput, type CreateRuleInput, type CreateWebhookInput, type Domain, type DomainVerification, type EmailLog, MailMask, type MailMaskConfig, MailMaskError, type Rule, type RuleAction, type RuleField, type RuleMatch, type SendEmailInput, type SendOptions, type SmtpCredential, type SmtpCredentialCreated, type Suppression, type UpdateAliasInput, type UpdateRuleInput, type UpdateWebhookInput, type UploadAttachmentInput, type UploadedAttachment, type Webhook, type WebhookCreated, type WebhookDelivery, type WebhookEvent, type WebhookPayload, type WebhookSignatureHeaders, verifyWebhookSignature };
+export { type Alias, type AliasCreated, type ApiKey, type AttachmentRef, type BulkJob, type BulkJobCreated, type BulkSendInput, type CreateAliasInput, type CreateRuleInput, type CreateWebhookInput, type DnsRecord, type Domain, type DomainCreated, type DomainVerification, type EmailLog, MailMask, type MailMaskConfig, MailMaskError, type MailboxCreated, type Rule, type RuleAction, type RuleField, type RuleMatch, type SendEmailInput, type SendOptions, type SmtpCredential, type SmtpCredentialCreated, type Suppression, type UpdateAliasInput, type UpdateRuleInput, type UpdateWebhookInput, type UploadAttachmentInput, type UploadedAttachment, type Webhook, type WebhookCreated, type WebhookDelivery, type WebhookEvent, type WebhookPayload, type WebhookSignatureHeaders, verifyWebhookSignature };

package/dist/index.js

@@ -65,7 +65,15 @@ var AliasesResource = class {
     return this.req(`/api/domains/${domainId}/alias`);
   }
   create(domainId, input) {
-    return this.req(`/api/domains/${domainId}/alias`, { method: "POST", body: JSON.stringify(input) });
+    return this.req(`/api/domains/${domainId}/alias`, { method: "POST", body: JSON.stringify({ ...input, destinations: input.destinations ?? [] }) });
+  }
+  /** Crea un buzón IMAP para una máscara existente. La contraseña sólo se devuelve aquí. */
+  createMailbox(domainId, alias) {
+    return this.req(`/api/domains/${domainId}/alias/${alias}/mailbox`, { method: "POST" });
+  }
+  /** Borra el buzón Y SU CORREO. La máscara debe conservar al menos un destino. */
+  deleteMailbox(domainId, alias) {
+    return this.req(`/api/domains/${domainId}/alias/${alias}/mailbox`, { method: "DELETE" });
   }
   update(domainId, alias, input) {
     return this.req(`/api/domains/${domainId}/alias/${alias}`, { method: "PUT", body: JSON.stringify(input) });

package/package.json

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