ts-mailkit 2.0.1 → 2.1.0

package/README.md

@@ -10,7 +10,7 @@ Works seamlessly in **Node.js**, **Cloudflare Workers** (`workerd`), **Bun**, **
 
 - **Type-Safe DTOs**: Strongly-typed Data Transfer Objects for transactional emails (verification, password reset, 2FA, magic links, newsletters).
 - **Pluggable Transports (`IEmailSender`)**: Decoupled transport adapter interface with built-in senders:
-  - `ZeptoMailHttpSender` (Zoho Mail transactional API via native `fetch`).
+  - `CpaasHttpSender` (Zoho CPaaS transactional API via native `fetch`; `ZeptoMailHttpSender` is a deprecated alias).
   - `MemoryEmailSender` (In-memory mock transport for unit and integration testing).
   - `ConsoleEmailSender` (Formatted terminal logger for local development).
 - **Zero Runtime Dependencies**: Core uses standard web APIs (global `fetch`), ensuring zero heavy dependencies and complete edge compatibility.
@@ -52,19 +52,19 @@ bun add ts-mailkit
 ### 1. Initialize Transport & Client
 
 ```ts
-import { createMailKit, ZeptoMailHttpSender, EmailTemplateFactory } from 'ts-mailkit';
+import { createMailKit, CpaasHttpSender, EmailTemplateFactory } from "ts-mailkit";
 
-// Configure the Zoho ZeptoMail HTTP transport
-const transport = new ZeptoMailHttpSender({
-  apiToken: process.env.ZEPTO_MAIL_TOKEN!,
-  apiHost: 'api.zeptomail.com', // or 'api.zeptomail.eu', 'api.zeptomail.in'
-  from: { address: 'noreply@yourdomain.com', name: 'Acme App' },
+// Configure the Zoho CPaaS HTTP transport
+const transport = new CpaasHttpSender({
+  apiToken: process.env.CPAAS_API_KEY!,
+  apiHost: "cpaas.zoho.com", // or 'cpaas.zoho.eu', 'cpaas.zoho.in'
+  from: { address: "noreply@yourdomain.com", name: "Acme App" },
 });
 
 // Initialize the MailKit client
 const mailer = createMailKit({
   transport,
-  defaultBrandName: 'Acme App',
+  defaultBrandName: "Acme App",
 });
 ```
 
@@ -73,14 +73,14 @@ const mailer = createMailKit({
 ```ts
 // 1. Create a strongly typed email verification DTO
 const verificationEmail = EmailTemplateFactory.createEmailVerification({
-  username: 'Alex',
-  verificationUrl: 'https://app.example.com/verify?token=xyz123',
-  otp: '482910',
+  username: "Alex",
+  verificationUrl: "https://app.example.com/verify?token=xyz123",
+  otp: "482910",
 });
 
 // 2. Dispatch via MailKit
-await mailer.send({
-  to: 'alex@example.com',
+await mailer.sendMail({
+  to: "alex@example.com",
   template: verificationEmail,
 });
 ```
@@ -94,43 +94,43 @@ await mailer.send({
 `EmailTemplateFactory` provides type-safe constructors for standard transactional patterns:
 
 ```ts
-import { EmailTemplateFactory } from 'ts-mailkit';
+import { EmailTemplateFactory } from "ts-mailkit";
 
 // Email Verification with OTP
 const verifyDto = EmailTemplateFactory.createEmailVerification({
-  username: 'Jordan',
-  verificationUrl: 'https://app.com/verify?token=abc',
-  otp: '123456',
+  username: "Jordan",
+  verificationUrl: "https://app.com/verify?token=abc",
+  otp: "123456",
 });
 
 // Password Reset
 const resetDto = EmailTemplateFactory.createPasswordReset({
-  username: 'Jordan',
-  resetUrl: 'https://app.com/reset?token=abc',
-  otp: '654321',
+  username: "Jordan",
+  resetUrl: "https://app.com/reset?token=abc",
+  otp: "654321",
 });
 
 // Two-Factor Authentication (2FA)
 const twoFactorDto = EmailTemplateFactory.create2FAEmail({
-  username: 'Jordan',
-  otp: '987654',
-  magicLink: 'https://app.com/2fa/magic?token=abc',
+  username: "Jordan",
+  otp: "987654",
+  magicLink: "https://app.com/2fa/magic?token=abc",
 });
 
 // Magic Link Sign-in
 const magicLinkDto = EmailTemplateFactory.createMagicLinkEmail({
-  username: 'Jordan',
-  magicLink: 'https://app.com/auth/magic?token=abc',
+  username: "Jordan",
+  magicLink: "https://app.com/auth/magic?token=abc",
 });
 
 // Newsletter / Announcement
 const newsDto = EmailTemplateFactory.createNewsLetter({
-  subject: 'Product Update - Fall 2026',
-  header: 'Introducing New Features',
-  body: 'Here is what our team shipped this month.',
-  imageUrl: 'https://cdn.example.com/hero.png',
-  actionUrl: 'https://app.com/blog/update',
-  actionText: 'Read Release Notes',
+  subject: "Product Update - Fall 2026",
+  header: "Introducing New Features",
+  body: "Here is what our team shipped this month.",
+  imageUrl: "https://cdn.example.com/hero.png",
+  actionUrl: "https://app.com/blog/update",
+  actionText: "Read Release Notes",
 });
 ```
 
@@ -140,16 +140,17 @@ You can instantiate `EmailTemplateFactory` with brand-level defaults:
 
 ```ts
 const tenantFactory = new EmailTemplateFactory({
-  brandName: 'St. Patrick High School',
-  logoUrl: 'https://school.edu/assets/logo.png',
-  securityMessage: 'If you did not make this request, contact our school IT administration immediately.',
+  brandName: "St. Patrick High School",
+  logoUrl: "https://school.edu/assets/logo.png",
+  securityMessage:
+    "If you did not make this request, contact our school IT administration immediately.",
   footer: (brand) => `© ${new Date().getFullYear()} ${brand}. Authorized educational portal.`,
 });
 
 const studentEmail = tenantFactory.createEmailVerification({
-  username: 'Student',
-  verificationUrl: 'https://school.edu/verify',
-  otp: '554433',
+  username: "Student",
+  verificationUrl: "https://school.edu/verify",
+  otp: "554433",
 });
 ```
 
@@ -158,10 +159,10 @@ Or pass a dynamic tenant resolver to `MailKit`:
 ```ts
 const mailer = createMailKit({
   transport,
-  defaultFrom: 'notifications@portal.edu',
+  defaultFrom: "notifications@portal.edu",
   brandNameResolver: async () => {
     // Dynamically retrieve active tenant brand from request context or DB
-    return 'Springfield Academy';
+    return "Springfield Academy";
   },
 });
 ```
@@ -171,10 +172,10 @@ const mailer = createMailKit({
 Easily write unit and integration tests without hitting third-party APIs or mocking network sockets:
 
 ```ts
-import { describe, it, expect, beforeEach } from 'vitest';
-import { createMailKit, MemoryEmailSender, EmailTemplateFactory } from 'ts-mailkit';
+import { describe, it, expect, beforeEach } from "vitest";
+import { createMailKit, MemoryEmailSender, EmailTemplateFactory } from "ts-mailkit";
 
-describe('User Registration Email', () => {
+describe("User Registration Email", () => {
   let memoryTransport: MemoryEmailSender;
   let mailer: ReturnType<typeof createMailKit>;
 
@@ -183,20 +184,20 @@ describe('User Registration Email', () => {
     mailer = createMailKit({ transport: memoryTransport });
   });
 
-  it('sends verification code to the registered user', async () => {
+  it("sends verification code to the registered user", async () => {
     const dto = EmailTemplateFactory.createEmailVerification({
-      username: 'Sam',
-      verificationUrl: 'https://app.com/verify?token=123',
-      otp: '889900',
+      username: "Sam",
+      verificationUrl: "https://app.com/verify?token=123",
+      otp: "889900",
     });
 
-    await mailer.send({ to: 'sam@example.com', template: dto });
+    await mailer.sendMail({ to: "sam@example.com", template: dto });
 
     expect(memoryTransport.count()).toBe(1);
     const sent = memoryTransport.getLastMail();
-    expect(sent?.subject).toBe('Verify Your Email Address');
-    expect(sent?.html).toContain('889900');
-    expect(sent?.text).toContain('Your verification code is: 889900');
+    expect(sent?.subject).toBe("Verify Your Email Address");
+    expect(sent?.html).toContain("889900");
+    expect(sent?.text).toContain("Your verification code is: 889900");
   });
 });
 ```
@@ -207,15 +208,15 @@ For custom HTML or plain-text messages. When `text` is omitted, an accessible pl
 
 ```ts
 await mailer.sendRaw({
-  to: [{ address: 'support@example.com', name: 'Support Team' }],
-  subject: 'Urgent System Alert',
-  html: '<h1>System Alert</h1><p>Database failover completed successfully.</p>',
+  to: [{ address: "support@example.com", name: "Support Team" }],
+  subject: "Urgent System Alert",
+  html: "<h1>System Alert</h1><p>Database failover completed successfully.</p>",
   // text is optional — auto-converted from html if omitted
   attachments: [
     {
-      filename: 'report.txt',
-      content: 'Database log summary...',
-      mimeType: 'text/plain',
+      filename: "report.txt",
+      content: "Database log summary...",
+      mimeType: "text/plain",
     },
   ],
 });
@@ -226,35 +227,85 @@ await mailer.sendRaw({
 If your application receives combined address strings like `"Jane Doe <jane@example.com>"`, use the standalone, tree-shakeable `parseEmailAddress` helper:
 
 ```ts
-import { parseEmailAddress } from 'ts-mailkit';
+import { parseEmailAddress } from "ts-mailkit";
 
-const recipient = parseEmailAddress('Jane Doe <jane@example.com>');
+const recipient = parseEmailAddress("Jane Doe <jane@example.com>");
 // => { address: 'jane@example.com', name: 'Jane Doe' }
 
-const simple = parseEmailAddress('jane@example.com');
+const simple = parseEmailAddress("jane@example.com");
 // => { address: 'jane@example.com' }
 ```
 
 ### 6. Pluggable Transports (`IEmailSender`)
 
-You can implement custom transports (e.g. SMTP, Resend, SendGrid, Postmark) by satisfying the `IEmailSender` interface:
+You can implement custom transports (e.g. SMTP, Resend, SendGrid, Postmark) by satisfying the `IEmailSender` interface. Bulk and provider-template capabilities are optional: implement `sendBulk`, `sendKnownTemplate`, and/or `sendBulkKnownTemplate` to enable them. `MailKit` throws a `ConfigurationError` if a method is called on a transport that does not implement it.
 
 ```ts
-import type { IEmailSender, SendMailOptions, SendResult } from 'ts-mailkit';
+import type { IEmailSender, SendMailOptions, SendResult } from "ts-mailkit";
 
 export class CustomSmtpSender implements IEmailSender {
-  readonly name = 'smtp';
+  readonly name = "smtp";
 
   async send(options: SendMailOptions): Promise<SendResult> {
     // Custom dispatch logic using your preferred protocol or client
     return {
       success: true,
-      messageId: 'custom-id-123',
+      messageId: "custom-id-123",
     };
   }
 }
 ```
 
+### 7. Bulk Messaging & Provider-Side Templates
+
+`MailKit` exposes four canonical send methods. Bulk methods hit the provider's batch endpoints directly (no client-side loops) and deliver an individual copy to each recipient.
+
+```ts
+// 1. Bulk manual template: one rendered DTO, delivered individually to every recipient.
+await mailer.sendBulkMail({
+  to: ["a@example.com", "b@example.com"],
+  template: newsletterDto,
+  trackClicks: true,
+  trackOpens: true,
+});
+
+// 2. Single provider-side template (uploaded to Zoho CPaaS / SendGrid beforehand).
+await mailer.sendKnownTemplate({
+  templateId: "welcome-email",
+  to: "alex@example.com",
+  mergeInfo: { user_name: "Alex" },
+});
+
+// 3. Bulk provider-side template with per-recipient merge data.
+await mailer.sendBulkKnownTemplate({
+  templateId: "welcome-email",
+  to: [
+    { address: "alex@example.com", name: "Alex", mergeInfo: { user_name: "Alex" } },
+    { address: "sam@example.com", name: "Sam", mergeInfo: { user_name: "Sam" } },
+  ],
+});
+```
+
+Set `CpaasHttpConfig.preferTemplateAlias: true` to send `template_alias` instead of `template_key`. Every transport returns a unified `SendResult` whose `rawResponse` field holds the provider's raw response (typed via the exported `CpaasSuccessResponse` / `CpaasErrorResponse` types).
+
+### 8. Building Upload-Ready Templates
+
+`buildHTMLTemplate` and `buildPlainTextTemplate` turn the canonical `EmailTemplateDto` into content you can upload to a messaging platform:
+
+```ts
+import { buildHTMLTemplate, buildPlainTextTemplate, EmailTemplateFactory } from "ts-mailkit";
+
+const dto = EmailTemplateFactory.createSimpleMessage({
+  subject: "Welcome",
+  header: "Hello",
+  body: "Thanks for joining.",
+});
+
+const html = buildHTMLTemplate(dto, { primaryColor: "#0f766e", maxWidth: "640px" });
+const text = buildPlainTextTemplate(dto);
+// Upload `html` / `text` as a provider-side template, then send with `sendKnownTemplate`.
+```
+
 ---
 
 ## Template Preview

package/dist/core/bulk-types.d.ts

@@ -0,0 +1,196 @@
+import type { EmailAttachment, Recipient, SendMailOptions } from "./types.js";
+import type { EmailTemplateDto } from "../templates/dto/index.js";
+/**
+ * A recipient with optional provider-side merge variables.
+ */
+export interface BulkRecipient {
+    address: string;
+    name?: string;
+    /**
+     * Provider-side merge variables (e.g. Zoho CPaaS `merge_info`).
+     */
+    mergeInfo?: Record<string, string>;
+}
+/**
+ * Transport-level batch of a single raw email content to many recipients.
+ *
+ * The provider delivers an individual copy to each recipient, so recipients
+ * are not exposed to one another.
+ */
+export interface BulkSendOptions extends SendMailOptions {
+    /**
+     * Enable or disable click tracking.
+     */
+    trackClicks?: boolean;
+    /**
+     * Enable or disable open tracking.
+     */
+    trackOpens?: boolean;
+    /**
+     * Verified bounce (Return-Path) address.
+     */
+    bounceAddress?: string;
+    /**
+     * Custom reference string to identify the email in your system.
+     */
+    clientReference?: string;
+}
+/**
+ * Options for sending a single email using a provider-side template.
+ */
+export interface KnownTemplateSendOptions {
+    /**
+     * Provider-side template identifier (e.g. Zoho `template_key`).
+     */
+    templateId: string;
+    /**
+     * Recipient email address.
+     */
+    to: Recipient;
+    /**
+     * Optional sender address override.
+     */
+    from?: Recipient;
+    /**
+     * Template variable substitutions.
+     */
+    mergeInfo?: Record<string, string>;
+    /**
+     * Optional CC recipients.
+     */
+    cc?: Recipient | Recipient[];
+    /**
+     * Optional BCC recipients.
+     */
+    bcc?: Recipient | Recipient[];
+    /**
+     * Optional Reply-To recipients.
+     */
+    replyTo?: Recipient | Recipient[];
+    /**
+     * Optional file attachments.
+     */
+    attachments?: EmailAttachment[];
+    /**
+     * Enable or disable click tracking.
+     */
+    trackClicks?: boolean;
+    /**
+     * Enable or disable open tracking.
+     */
+    trackOpens?: boolean;
+    /**
+     * Verified bounce (Return-Path) address.
+     */
+    bounceAddress?: string;
+    /**
+     * Custom reference string to identify the email in your system.
+     */
+    clientReference?: string;
+}
+/**
+ * Options for sending a batch of emails using a provider-side template.
+ *
+ * Each recipient may carry its own `mergeInfo` so the provider can
+ * personalize the template per recipient.
+ */
+export interface BulkKnownTemplateSendOptions {
+    /**
+     * Provider-side template identifier (e.g. Zoho `template_key`).
+     */
+    templateId: string;
+    /**
+     * Recipients, each with optional per-recipient merge variables.
+     */
+    to: BulkRecipient[];
+    /**
+     * Optional sender address override.
+     */
+    from?: Recipient;
+    /**
+     * Optional CC recipients.
+     */
+    cc?: Recipient | Recipient[];
+    /**
+     * Optional BCC recipients.
+     */
+    bcc?: Recipient | Recipient[];
+    /**
+     * Optional Reply-To recipients.
+     */
+    replyTo?: Recipient | Recipient[];
+    /**
+     * Optional file attachments.
+     */
+    attachments?: EmailAttachment[];
+    /**
+     * Enable or disable click tracking.
+     */
+    trackClicks?: boolean;
+    /**
+     * Enable or disable open tracking.
+     */
+    trackOpens?: boolean;
+    /**
+     * Verified bounce (Return-Path) address.
+     */
+    bounceAddress?: string;
+    /**
+     * Custom reference string to identify the email in your system.
+     */
+    clientReference?: string;
+}
+/**
+ * Client-level options for sending a bulk email using the in-built template DTO.
+ */
+export interface SendBulkMailOptions {
+    /**
+     * Templated email DTO to render and send to every recipient.
+     */
+    template: EmailTemplateDto;
+    /**
+     * One or more recipient email addresses.
+     */
+    to: Recipient | Recipient[];
+    /**
+     * Optional sender address override.
+     */
+    from?: Recipient;
+    /**
+     * Optional CC recipients.
+     */
+    cc?: Recipient | Recipient[];
+    /**
+     * Optional BCC recipients.
+     */
+    bcc?: Recipient | Recipient[];
+    /**
+     * Optional Reply-To recipients.
+     */
+    replyTo?: Recipient | Recipient[];
+    /**
+     * Optional file attachments.
+     */
+    attachments?: EmailAttachment[];
+    /**
+     * Optional custom headers.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Optional tags for tracking.
+     */
+    tags?: string[];
+    /**
+     * Optional metadata.
+     */
+    metadata?: Record<string, string>;
+    /**
+     * Enable or disable click tracking.
+     */
+    trackClicks?: boolean;
+    /**
+     * Enable or disable open tracking.
+     */
+    trackOpens?: boolean;
+}
+//# sourceMappingURL=bulk-types.d.ts.map

package/dist/core/bulk-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bulk-types.d.ts","sourceRoot":"","sources":["../../src/core/bulk-types.ts"],"names":[],"mappings":"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"}

package/dist/core/client.d.ts

@@ -1,7 +1,8 @@
-import type { IEmailSender } from '../transports/sender.interface.js';
-import type { IEmailRenderer, RenderedEmail } from '../renderers/renderer.interface.js';
-import type { EmailTemplateDto } from '../templates/dto/index.js';
-import { type Recipient, type SendMailOptions, type SendResult } from './types.js';
+import type { IEmailSender } from "../transports/sender.interface.js";
+import type { IEmailRenderer, RenderedEmail } from "../renderers/renderer.interface.js";
+import type { EmailTemplateDto } from "../templates/dto/index.js";
+import { type Recipient, type SendMailOptions, type SendResult } from "./types.js";
+import type { BulkKnownTemplateSendOptions, KnownTemplateSendOptions, SendBulkMailOptions } from "./bulk-types.js";
 export interface SendTemplateOptions {
     /**
      * One or more recipient email addresses.
@@ -38,7 +39,7 @@ export interface SendTemplateOptions {
     /**
      * Optional file attachments.
      */
-    attachments?: SendMailOptions['attachments'];
+    attachments?: SendMailOptions["attachments"];
     /**
      * Optional custom headers.
      */
@@ -98,13 +99,44 @@ export declare class MailKit {
      *
      * Example:
      * ```ts
-     * await mailer.send({
+     * await mailer.sendMail({
      *   to: 'user@example.com',
      *   template: myDto,
      * });
      * ```
      */
+    sendMail(options: SendTemplateOptions): Promise<SendResult>;
+    /**
+     * @deprecated Use {@link sendMail} instead.
+     */
     send(options: SendTemplateOptions): Promise<SendResult>;
+    /**
+     * Sends a bulk email using a strongly-typed template DTO.
+     *
+     * The transport delivers an individual copy to each recipient, so
+     * recipients are not exposed to one another. Per-recipient personalization
+     * is available via {@link sendBulkKnownTemplate}.
+     *
+     * Example:
+     * ```ts
+     * await mailer.sendBulkMail({
+     *   to: ['a@example.com', 'b@example.com'],
+     *   template: myDto,
+     * });
+     * ```
+     */
+    sendBulkMail(options: SendBulkMailOptions): Promise<SendResult>;
+    /**
+     * Sends a single email using a provider-side template.
+     */
+    sendKnownTemplate(options: KnownTemplateSendOptions): Promise<SendResult>;
+    /**
+     * Sends a bulk email using a provider-side template with optional
+     * per-recipient merge data.
+     */
+    sendBulkKnownTemplate(options: BulkKnownTemplateSendOptions): Promise<SendResult>;
+    private resolveFromName;
+    private applyFromName;
     /**
      * Dispatches a raw, pre-rendered email directly through the transport.
      * If `options.text` is omitted, plain text is automatically derived from `options.html`.

package/dist/core/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/core/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AACtE,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAC;AAGxF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAClE,OAAO,EAGL,KAAK,SAAS,EACd,KAAK,eAAe,EACpB,KAAK,UAAU,EAChB,MAAM,YAAY,CAAC;AAGpB,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,EAAE,EAAE,SAAS,GAAG,SAAS,EAAE,CAAC;IAC5B;;OAEG;IACH,QAAQ,EAAE,gBAAgB,CAAC;IAC3B;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;OAEG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB;;OAEG;IACH,EAAE,CAAC,EAAE,SAAS,GAAG,SAAS,EAAE,CAAC;IAC7B;;OAEG;IACH,GAAG,CAAC,EAAE,SAAS,GAAG,SAAS,EAAE,CAAC;IAC9B;;OAEG;IACH,OAAO,CAAC,EAAE,SAAS,GAAG,SAAS,EAAE,CAAC;IAClC;;OAEG;IACH,WAAW,CAAC,EAAE,eAAe,CAAC,aAAa,CAAC,CAAC;IAC7C;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,SAAS,EAAE,YAAY,CAAC;IACxB;;OAEG;IACH,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B;;OAEG;IACH,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB;;OAEG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC;CACpD;AAED;;GAEG;AACH,qBAAa,OAAO;IAClB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiB;IAC1C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAY;IACzC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAiC;IAEpE,YAAY,OAAO,EAAE,cAAc,EASlC;IAED;;OAEG;IACH,YAAY,IAAI,YAAY,CAE3B;IAED;;OAEG;IACG,MAAM,CAAC,QAAQ,EAAE,gBAAgB,GAAG,OAAO,CAAC,aAAa,CAAC,CAE/D;IAED;;;;;;;;;;OAUG;IACG,IAAI,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,UAAU,CAAC,CA8C5D;IAED;;;OAGG;IACG,OAAO,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,UAAU,CAAC,CAQ3D;CACF;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAE9D"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/core/client.ts"],"names":[],"mappings":"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"}

package/dist/core/errors.d.ts

@@ -17,11 +17,14 @@ export declare class TransportError extends MailKitError {
     readonly transportName: string;
     readonly statusCode?: number;
     readonly responseBody?: string;
+    /** Parsed raw provider response, when available. */
+    readonly rawResponse?: unknown;
     readonly cause?: unknown;
     constructor(message: string, options: {
         transportName: string;
         statusCode?: number;
         responseBody?: string;
+        rawResponse?: unknown;
         cause?: unknown;
     });
 }

package/dist/core/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,YAAa,SAAQ,KAAK;IACrC,YAAY,OAAO,EAAE,MAAM,EAI1B;CACF;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,YAAY;IAClD,YAAY,OAAO,EAAE,MAAM,EAI1B;CACF;AAED;;GAEG;AACH,qBAAa,cAAe,SAAQ,YAAY;IAC9C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IAEzB,YACE,OAAO,EAAE,MAAM,EACf,OAAO,EAAE;QACP,aAAa,EAAE,MAAM,CAAC;QACtB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB,EASF;CACF;AAED;;GAEG;AACH,qBAAa,aAAc,SAAQ,YAAY;IAC7C,YAAY,OAAO,EAAE,MAAM,EAI1B;CACF"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,YAAa,SAAQ,KAAK;IACrC,YAAY,OAAO,EAAE,MAAM,EAI1B;CACF;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,YAAY;IAClD,YAAY,OAAO,EAAE,MAAM,EAI1B;CACF;AAED;;GAEG;AACH,qBAAa,cAAe,SAAQ,YAAY;IAC9C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,oDAAoD;IACpD,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IAEzB,YACE,OAAO,EAAE,MAAM,EACf,OAAO,EAAE;QACP,aAAa,EAAE,MAAM,CAAC;QACtB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,WAAW,CAAC,EAAE,OAAO,CAAC;QACtB,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB,EAUF;CACF;AAED;;GAEG;AACH,qBAAa,aAAc,SAAQ,YAAY;IAC7C,YAAY,OAAO,EAAE,MAAM,EAI1B;CACF"}

package/dist/core/types.d.ts

@@ -66,6 +66,11 @@ export interface SendMailOptions {
 export interface SendResult {
     success: boolean;
     messageId?: string;
+    /** Raw provider response (e.g. Zoho CPaaS JSON body). */
+    rawResponse?: unknown;
+    /**
+     * @deprecated Use `rawResponse` instead.
+     */
     response?: unknown;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/core/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,MAAM,MAAM,SAAS,GACjB,MAAM,GACN,YAAY,GACZ;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAErC;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,CAa7D;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,SAAS,GAAG,YAAY,CAcrE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,CAAC,EAAE,SAAS,GAAG,SAAS,EAAE,GACnC,YAAY,EAAE,CAIhB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB;;OAEG;IACH,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,SAAS,GAAG,SAAS,EAAE,CAAC;IAC5B,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,EAAE,CAAC,EAAE,SAAS,GAAG,SAAS,EAAE,CAAC;IAC7B,GAAG,CAAC,EAAE,SAAS,GAAG,SAAS,EAAE,CAAC;IAC9B,OAAO,CAAC,EAAE,SAAS,GAAG,SAAS,EAAE,CAAC;IAClC,WAAW,CAAC,EAAE,eAAe,EAAE,CAAC;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,YAAY,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjF;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,CAa7D;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,SAAS,GAAG,YAAY,CAcrE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,CAAC,EAAE,SAAS,GAAG,SAAS,EAAE,GAAG,YAAY,EAAE,CAIxF;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB;;OAEG;IACH,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,SAAS,GAAG,SAAS,EAAE,CAAC;IAC5B,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,EAAE,CAAC,EAAE,SAAS,GAAG,SAAS,EAAE,CAAC;IAC7B,GAAG,CAAC,EAAE,SAAS,GAAG,SAAS,EAAE,CAAC;IAC9B,OAAO,CAAC,EAAE,SAAS,GAAG,SAAS,EAAE,CAAC;IAClC,WAAW,CAAC,EAAE,eAAe,EAAE,CAAC;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;OAEG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB"}