mailchannels-sdk 0.7.6 → 0.7.7

package/README.md

@@ -29,6 +29,7 @@ This library provides a simple way to interact with the [MailChannels API](https
 - 📐 [Naming Conventions](#naming-conventions)
 - ⚖️ [License](#license)
 - 💻 [Development](#development)
+- 🧪 [Local simulator](#local-simulator)
 
 ## <a name="features">🚀 Features</a>
 
@@ -43,6 +44,7 @@ Some of the things you can do with the SDK:
 - Webhook notifications
 - Manage sub-accounts
 - Retrieve metrics
+- Inspect webhook delivery batches
 - Handle suppressions
 - Configure inbound domains
 - Manage account and recipient lists
@@ -130,12 +132,72 @@ pnpm test:watch
 # Run typecheck
 pnpm test:types
 
+# Refresh API parity fixtures
+pnpm parity:fixtures
+
+# Run the local Email API simulator
+pnpm simulate:email-api
+
 # Release new version
 pnpm release
 ```
 
 </details>
 
+## <a name="local-simulator">🧪 Local simulator</a>
+
+This repo includes a small local MailChannels Email API simulator at [scripts/email-api-simulator.mjs](./scripts/email-api-simulator.mjs). It keeps state in memory and emulates the SDK-supported Email API endpoints so you can test your application without calling the real MailChannels service.
+
+### Start the simulator
+
+```sh
+# default: http://127.0.0.1:8787
+pnpm simulate:email-api
+```
+
+You can override the bind address with environment variables:
+
+```sh
+MAILCHANNELS_SIMULATOR_HOST=127.0.0.1 MAILCHANNELS_SIMULATOR_PORT=8787 pnpm simulate:email-api
+```
+
+### Point the SDK at the simulator
+
+Use the optional `baseUrl` constructor option when creating the client:
+
+```ts
+import { MailChannels } from 'mailchannels-sdk'
+
+const mailchannels = new MailChannels('local-test-key', {
+  baseUrl: 'http://127.0.0.1:8787'
+})
+
+const { data, error } = await mailchannels.emails.send({
+  from: 'sender@example.com',
+  to: 'recipient@example.com',
+  subject: 'Hello from the simulator',
+  html: '<p>Local test</p>'
+})
+```
+
+### What the simulator supports today
+
+- Email sends and async sends
+- Domain checks
+- DKIM key create, list, rotate, and update
+- Webhook enrollment, listing, validation, signing key lookup, and batch inspection
+- Sub-account lifecycle, API keys, SMTP passwords, limits, and usage
+- Engagement, performance, recipient behaviour, sender, volume, and usage metrics
+- Suppression create, list, and delete
+
+### Current limitations
+
+- State is in-memory only and is reset when the process stops
+- Any non-empty `X-API-Key` is accepted, with separate in-memory state per API key
+- Webhook responses are simulated locally, but the simulator does not yet emit real webhook callbacks to your application
+
+The next planned expansion is outbound webhook delivery so client applications can test webhook ingestion flows against the simulator as well.
+
 <!-- Badges -->
 [npm-version-src]: https://img.shields.io/npm/v/mailchannels-sdk.svg?style=flat&colorA=070a30&colorB=35a047
 [npm-version-href]: https://npmjs.com/package/mailchannels-sdk

package/dist/mailchannels.d.mts

@@ -1,8 +1,16 @@
 import { FetchOptions } from "ofetch";
+interface MailChannelsClientOptions {
+  /**
+   * Override the MailChannels API base URL.
+   * Useful for local testing against a simulator.
+   * @default "https://api.mailchannels.net"
+   */
+  baseUrl?: string;
+}
 declare class MailChannelsClient {
   #private;
-  private static BASE_URL;
-  constructor(key: string);
+  private static readonly DEFAULT_BASE_URL;
+  constructor(key: string, options?: MailChannelsClientOptions);
   protected _fetch<T>(path: string, options?: FetchOptions<"json">): Promise<T>;
   post<T>(path: string, options?: Omit<FetchOptions<"json">, "method">): Promise<T>;
   get<T>(path: string, options?: Omit<FetchOptions<"json">, "method">): Promise<T>;
@@ -79,6 +87,63 @@ interface EmailsSendTracking {
    */
   open?: boolean;
 }
+type EmailsSendRecipientInput = EmailsSendRecipient[] | EmailsSendRecipient | string[] | string;
+interface EmailsSendDkim {
+  /**
+   * Domain used for DKIM signing.
+   */
+  domain?: string;
+  /**
+   * DKIM private key encoded in Base64.
+   */
+  privateKey?: string;
+  /**
+   * DKIM selector in the domain DNS records.
+   */
+  selector?: string;
+}
+interface EmailsSendPersonalization {
+  /**
+   * The BCC recipients for this personalization.
+   */
+  bcc?: EmailsSendRecipientInput;
+  /**
+   * The CC recipients for this personalization.
+   */
+  cc?: EmailsSendRecipientInput;
+  /**
+   * DKIM settings for this personalization.
+   */
+  dkim?: EmailsSendDkim;
+  /**
+   * Optional envelope sender for this personalization.
+   */
+  envelopeFrom?: EmailsSendRecipient | string;
+  /**
+   * Optional sender override for this personalization.
+   */
+  from?: EmailsSendRecipient | string;
+  /**
+   * Custom headers for this personalization.
+   */
+  headers?: Record<string, string>;
+  /**
+   * Reply-to override for this personalization.
+   */
+  replyTo?: EmailsSendRecipient | string;
+  /**
+   * Subject override for this personalization.
+   */
+  subject?: string;
+  /**
+   * The recipients for this personalization.
+   */
+  to: EmailsSendRecipientInput;
+  /**
+   * Template variables for this personalization.
+   */
+  mustaches?: Record<string, unknown>;
+}
 interface EmailsSendOptionsBase {
   /**
    * An array of attachments to be sent with the email.
@@ -104,7 +169,7 @@ interface EmailsSendOptionsBase {
    * @example
    * 'Name <email@example.com>'
    */
-  bcc?: EmailsSendRecipient[] | EmailsSendRecipient | string[] | string;
+  bcc?: EmailsSendRecipientInput;
   /**
    * The CC recipients of the email. Can be an array of email addresses or an array of objects with email and name properties or a single email address string or an object with email and name properties.
    * @example
@@ -121,24 +186,11 @@ interface EmailsSendOptionsBase {
    * @example
    * 'Name <email@example.com>'
    */
-  cc?: EmailsSendRecipient[] | EmailsSendRecipient | string[] | string;
+  cc?: EmailsSendRecipientInput;
   /**
    * The DKIM settings for the email.
    */
-  dkim?: {
-    /**
-     * Domain used for DKIM signing.
-     */
-    domain: string;
-    /**
-     * DKIM private key encoded in Base64.
-     */
-    privateKey?: string;
-    /**
-     * DKIM selector in the domain DNS records.
-     */
-    selector: string;
-  };
+  dkim?: EmailsSendDkim;
   /**
    * Optional envelope sender address. If not set, the envelope sender defaults to the `from.email` field. Can be overridden per-personalization. Only the email portion is used; the name field is ignored.
    * @example
@@ -168,6 +220,10 @@ interface EmailsSendOptionsBase {
    * - **Case sensitivity**: Headers are treated as case-insensitive. If multiple headers differ only by case, only one will be used, with no guarantee of which one.
    */
   headers?: Record<string, string>;
+  /**
+   * Explicit personalization objects. Use this for advanced MailChannels payloads with multiple recipient groups or per-personalization overrides.
+   */
+  personalizations?: EmailsSendPersonalization[];
   /**
    * The recipient of the email. Can be an array of email addresses or an array of objects with `email` and `name` properties or a single email address string or an object with `email` and `name` properties.
    * @example
@@ -184,7 +240,7 @@ interface EmailsSendOptionsBase {
    * @example
    * 'Name <email@example.com>'
    */
-  to: EmailsSendRecipient[] | EmailsSendRecipient | string[] | string;
+  to?: EmailsSendRecipientInput;
   /**
    * Adjust open and click tracking for the message. Please note that enabling tracking for your messages requires a subscription that supports open and click tracking.
    *
@@ -227,7 +283,20 @@ interface EmailsSendOptionsBase {
    */
   transactional?: boolean;
 }
-type EmailsSendOptions = EmailsSendOptionsBase & ({
+type EmailsSendTargetOptions = {
+  personalizations: EmailsSendPersonalization[];
+  to?: never;
+  cc?: never;
+  bcc?: never;
+  mustaches?: never;
+} | {
+  personalizations?: never;
+  to: EmailsSendRecipientInput;
+  cc?: EmailsSendRecipientInput;
+  bcc?: EmailsSendRecipientInput;
+  mustaches?: Record<string, unknown>;
+};
+type EmailsSendOptions = EmailsSendOptionsBase & EmailsSendTargetOptions & ({
   /**
    * The HTML content of the email.
    * @example
@@ -2077,6 +2146,6 @@ declare class MailChannels extends MailChannelsClient {
   readonly lists: Lists;
   readonly users: Users;
   readonly service: Service;
-  constructor(key: string);
+  constructor(key: string, options?: MailChannelsClientOptions);
 }
-export { DataResponse, Domains, DomainsBulkCreateLoginLinks, DomainsBulkCreateLoginLinksResponse, DomainsBulkProvisionOptions, DomainsBulkProvisionResponse, DomainsCreateLoginLink, DomainsCreateLoginLinkResponse, DomainsData, DomainsDownstreamAddress, DomainsListDownstreamAddressesOptions, DomainsListDownstreamAddressesResponse, DomainsListOptions, DomainsListResponse, DomainsProvisionOptions, DomainsProvisionResponse, Emails, EmailsCheckDomainOptions, EmailsCheckDomainResponse, EmailsCheckDomainVerdict, EmailsCreateDkimKeyOptions, EmailsCreateDkimKeyResponse, EmailsDkimKey, EmailsDkimKeyStatus, EmailsGetDkimKeysOptions, EmailsGetDkimKeysResponse, EmailsRotateDkimKeyOptions, EmailsRotateDkimKeyResponse, EmailsSendAsyncResponse, EmailsSendAttachment, EmailsSendOptions, EmailsSendRecipient, EmailsSendResponse, EmailsSendTracking, EmailsUpdateDkimKeyOptions, ErrorResponse, ListEntriesResponse, ListEntry, ListEntryOptions, ListEntryResponse, ListNames, Lists, MailChannels, MailChannelsClient, Metrics, MetricsBucket, MetricsEngagement, MetricsEngagementResponse, MetricsOptions, MetricsPerformance, MetricsPerformanceResponse, MetricsRecipientBehaviour, MetricsRecipientBehaviourResponse, MetricsSenders, MetricsSendersOptions, MetricsSendersResponse, MetricsSendersType, MetricsUsageResponse, MetricsVolume, MetricsVolumeResponse, Service, ServiceReportOptions, ServiceSubscriptionsResponse, SubAccounts, SubAccountsAccount, SubAccountsApiKey, SubAccountsCreateApiKeyResponse, SubAccountsCreateResponse, SubAccountsCreateSmtpPasswordResponse, SubAccountsLimit, SubAccountsLimitResponse, SubAccountsListApiKeyOptions, SubAccountsListApiKeyResponse, SubAccountsListOptions, SubAccountsListResponse, SubAccountsListSmtpPasswordResponse, SubAccountsSmtpPassword, SubAccountsUsage, SubAccountsUsageResponse, SuccessResponse, Suppressions, SuppressionsCreateOptions, SuppressionsListEntry, SuppressionsListOptions, SuppressionsListResponse, SuppressionsSource, SuppressionsTypes, Users, UsersCreateOptions, UsersCreateResponse, WebhookEvent, WebhookEventClick, WebhookEventComplained, WebhookEventDelivered, WebhookEventDropped, WebhookEventHardBounced, WebhookEventOpen, WebhookEventProcessed, WebhookEventSoftBounced, WebhookEventTest, WebhookEventType, WebhookEventUnsubscribed, WebhookEvents, Webhooks, WebhooksBatch, WebhooksBatchResponseStatus, WebhooksBatchStatus, WebhooksBatchesOptions, WebhooksBatchesResponse, WebhooksListResponse, WebhooksSigningKeyResponse, WebhooksValidateResponse, WebhooksVerifyOptions };
+export { DataResponse, Domains, DomainsBulkCreateLoginLinks, DomainsBulkCreateLoginLinksResponse, DomainsBulkProvisionOptions, DomainsBulkProvisionResponse, DomainsCreateLoginLink, DomainsCreateLoginLinkResponse, DomainsData, DomainsDownstreamAddress, DomainsListDownstreamAddressesOptions, DomainsListDownstreamAddressesResponse, DomainsListOptions, DomainsListResponse, DomainsProvisionOptions, DomainsProvisionResponse, Emails, EmailsCheckDomainOptions, EmailsCheckDomainResponse, EmailsCheckDomainVerdict, EmailsCreateDkimKeyOptions, EmailsCreateDkimKeyResponse, EmailsDkimKey, EmailsDkimKeyStatus, EmailsGetDkimKeysOptions, EmailsGetDkimKeysResponse, EmailsRotateDkimKeyOptions, EmailsRotateDkimKeyResponse, EmailsSendAsyncResponse, EmailsSendAttachment, EmailsSendDkim, EmailsSendOptions, EmailsSendPersonalization, EmailsSendRecipient, EmailsSendRecipientInput, EmailsSendResponse, EmailsSendTracking, EmailsUpdateDkimKeyOptions, ErrorResponse, ListEntriesResponse, ListEntry, ListEntryOptions, ListEntryResponse, ListNames, Lists, MailChannels, MailChannelsClient, type MailChannelsClientOptions, Metrics, MetricsBucket, MetricsEngagement, MetricsEngagementResponse, MetricsOptions, MetricsPerformance, MetricsPerformanceResponse, MetricsRecipientBehaviour, MetricsRecipientBehaviourResponse, MetricsSenders, MetricsSendersOptions, MetricsSendersResponse, MetricsSendersType, MetricsUsageResponse, MetricsVolume, MetricsVolumeResponse, Service, ServiceReportOptions, ServiceSubscriptionsResponse, SubAccounts, SubAccountsAccount, SubAccountsApiKey, SubAccountsCreateApiKeyResponse, SubAccountsCreateResponse, SubAccountsCreateSmtpPasswordResponse, SubAccountsLimit, SubAccountsLimitResponse, SubAccountsListApiKeyOptions, SubAccountsListApiKeyResponse, SubAccountsListOptions, SubAccountsListResponse, SubAccountsListSmtpPasswordResponse, SubAccountsSmtpPassword, SubAccountsUsage, SubAccountsUsageResponse, SuccessResponse, Suppressions, SuppressionsCreateOptions, SuppressionsListEntry, SuppressionsListOptions, SuppressionsListResponse, SuppressionsSource, SuppressionsTypes, Users, UsersCreateOptions, UsersCreateResponse, WebhookEvent, WebhookEventClick, WebhookEventComplained, WebhookEventDelivered, WebhookEventDropped, WebhookEventHardBounced, WebhookEventOpen, WebhookEventProcessed, WebhookEventSoftBounced, WebhookEventTest, WebhookEventType, WebhookEventUnsubscribed, WebhookEvents, Webhooks, WebhooksBatch, WebhooksBatchResponseStatus, WebhooksBatchStatus, WebhooksBatchesOptions, WebhooksBatchesResponse, WebhooksListResponse, WebhooksSigningKeyResponse, WebhooksValidateResponse, WebhooksVerifyOptions };

package/dist/mailchannels.mjs

@@ -2,10 +2,12 @@ import { $fetch } from "ofetch";
 import { subtle } from "node:crypto";
 import { Buffer } from "node:buffer";
 var MailChannelsClient = class MailChannelsClient {
-	static BASE_URL = "https://api.mailchannels.net";
+	static DEFAULT_BASE_URL = "https://api.mailchannels.net";
+	#baseUrl;
 	#headers;
-	constructor(key) {
+	constructor(key, options = {}) {
 		if (!key) throw new Error("Missing MailChannels API key.");
+		this.#baseUrl = options.baseUrl || MailChannelsClient.DEFAULT_BASE_URL;
 		this.#headers = {
 			"X-API-Key": key,
 			"Accept": "application/json",
@@ -14,7 +16,7 @@ var MailChannelsClient = class MailChannelsClient {
 	}
 	async _fetch(path, options) {
 		return $fetch(path, {
-			baseURL: MailChannelsClient.BASE_URL,
+			baseURL: this.#baseUrl,
 			...options,
 			headers: {
 				...this.#headers,
@@ -146,75 +148,175 @@ const mapBuckets = (arr) => {
 		periodStart: period_start
 	}));
 };
+const RESERVED_HEADER_NAMES = new Set([
+	"authentication-results",
+	"bcc",
+	"cc",
+	"content-transfer-encoding",
+	"content-type",
+	"dkim-signature",
+	"from",
+	"message-id",
+	"received",
+	"reply-to",
+	"subject",
+	"to"
+]);
+const getRecipientCount = (recipients) => recipients?.length || 0;
+const validateHeaderMap = (headers, label) => {
+	if (!headers) return null;
+	const seenHeaders = /* @__PURE__ */ new Set();
+	for (const [headerName, headerValue] of Object.entries(headers)) {
+		if (typeof headerValue !== "string") return `${label} header '${headerName}' must have a string value.`;
+		const normalizedHeaderName = headerName.toLowerCase();
+		if (seenHeaders.has(normalizedHeaderName)) return `${label} headers must be unique when compared case-insensitively.`;
+		if (RESERVED_HEADER_NAMES.has(normalizedHeaderName)) return `${label} headers cannot include the reserved header '${headerName}'.`;
+		seenHeaders.add(normalizedHeaderName);
+	}
+	return null;
+};
+const validateSendDkim = (dkim, label) => {
+	if (!dkim) return null;
+	if (dkim.domain && !dkim.selector) return `${label} DKIM domain requires a selector.`;
+	if (dkim.privateKey && (!dkim.domain || !dkim.selector)) return `${label} DKIM privateKey requires both a domain and selector.`;
+	return null;
+};
+const mapDkimKey = (key) => ({
+	algorithm: key.algorithm,
+	createdAt: key.created_at,
+	dnsRecords: key.dkim_dns_records,
+	domain: key.domain,
+	gracePeriodExpiresAt: key.gracePeriodExpiresAt,
+	length: key.key_length,
+	publicKey: key.public_key,
+	retiresAt: key.retiresAt,
+	selector: key.selector,
+	status: key.status,
+	statusModifiedAt: key.status_modified_at
+});
+const mapDkim = (dkim) => ({
+	dkim_domain: dkim?.domain,
+	dkim_private_key: dkim?.privateKey ? stripPemHeaders(dkim.privateKey) : void 0,
+	dkim_selector: dkim?.selector
+});
+const mapPersonalization = (personalization, index) => {
+	const to = parseArrayRecipients(personalization.to);
+	if (!to || !to.length) return `Personalization at index ${index} must include at least one recipient in the \`to\` field.`;
+	if (to.length > 1e3) return `Personalization at index ${index} cannot include more than 1000 \`to\` recipients.`;
+	const cc = parseArrayRecipients(personalization.cc);
+	if (cc && cc.length > 1e3) return `Personalization at index ${index} cannot include more than 1000 \`cc\` recipients.`;
+	const bcc = parseArrayRecipients(personalization.bcc);
+	if (bcc && bcc.length > 1e3) return `Personalization at index ${index} cannot include more than 1000 \`bcc\` recipients.`;
+	const headerError = validateHeaderMap(personalization.headers, `Personalization at index ${index}`);
+	if (headerError) return headerError;
+	const dkimError = validateSendDkim(personalization.dkim, `Personalization at index ${index}`);
+	if (dkimError) return dkimError;
+	return {
+		bcc,
+		cc,
+		...mapDkim(personalization.dkim),
+		dynamic_template_data: personalization.mustaches,
+		envelope_from: parseRecipient(personalization.envelopeFrom),
+		from: parseRecipient(personalization.from),
+		headers: personalization.headers,
+		reply_to: parseRecipient(personalization.replyTo),
+		subject: personalization.subject,
+		to
+	};
+};
+const buildSendPayload = (options) => {
+	const { from, html, text } = options;
+	const parsedFrom = parseRecipient(from);
+	if (!parsedFrom || !parsedFrom.email) return "No sender provided. Use the `from` option to specify a sender";
+	if (!text && !html) return "No email content provided";
+	if (options.attachments && options.attachments.length > 1e3) return "The maximum number of attachments is 1000.";
+	if (options.campaignId && (options.campaignId.length > 48 || /\s/.test(options.campaignId))) return "campaignId must be 48 characters or fewer and must not contain spaces.";
+	const rootHeaderError = validateHeaderMap(options.headers, "Root");
+	if (rootHeaderError) return rootHeaderError;
+	const rootDkimError = validateSendDkim(options.dkim, "Root");
+	if (rootDkimError) return rootDkimError;
+	let personalizations;
+	if (options.personalizations) {
+		if (!options.personalizations.length) return "At least one personalization must be provided.";
+		if (options.personalizations.length > 1e3) return "The maximum number of personalizations is 1000.";
+		const mapped = options.personalizations.map(mapPersonalization);
+		const error = mapped.find((item) => typeof item === "string");
+		if (error) return error;
+		personalizations = mapped;
+	} else {
+		const parsedTo = parseArrayRecipients(options.to);
+		if (!parsedTo || !parsedTo.length) return "No recipients provided. Use the `to` option to specify at least one recipient";
+		if (parsedTo.length > 1e3) return "The maximum number of `to` recipients is 1000.";
+		const parsedCc = parseArrayRecipients(options.cc);
+		if (parsedCc && parsedCc.length > 1e3) return "The maximum number of `cc` recipients is 1000.";
+		const parsedBcc = parseArrayRecipients(options.bcc);
+		if (parsedBcc && parsedBcc.length > 1e3) return "The maximum number of `bcc` recipients is 1000.";
+		personalizations = [{
+			bcc: parsedBcc,
+			cc: parsedCc,
+			dynamic_template_data: options.mustaches,
+			to: parsedTo
+		}];
+	}
+	if (options.transactional === false) {
+		if (!personalizations.every((personalization) => {
+			const personalizationDkim = personalization.dkim_selector;
+			const rootDkim = options.dkim?.selector;
+			return Boolean(personalizationDkim || rootDkim);
+		})) return "Non-transactional messages must be DKIM signed.";
+		if (personalizations.some((personalization) => {
+			return getRecipientCount(personalization.to) + getRecipientCount(personalization.cc) + getRecipientCount(personalization.bcc) !== 1;
+		})) return "Non-transactional messages must have exactly one recipient per personalization.";
+	}
+	const content = [];
+	const template_type = Boolean(options.mustaches) || Boolean(options.personalizations?.some((personalization) => personalization.mustaches)) ? "mustache" : void 0;
+	if (text) content.push({
+		type: "text/plain",
+		value: text,
+		template_type
+	});
+	if (html) content.push({
+		type: "text/html",
+		value: html,
+		template_type
+	});
+	return {
+		attachments: options.attachments,
+		campaign_id: options.campaignId,
+		...mapDkim(options.dkim),
+		envelope_from: parseRecipient(options.envelopeFrom),
+		personalizations,
+		headers: options.headers,
+		reply_to: parseRecipient(options.replyTo),
+		from: parsedFrom,
+		subject: options.subject,
+		content,
+		tracking_settings: options.tracking ? {
+			click_tracking: typeof options.tracking.click === "boolean" ? { enable: options.tracking.click } : void 0,
+			open_tracking: typeof options.tracking.open === "boolean" ? { enable: options.tracking.open } : void 0
+		} : void 0,
+		transactional: options.transactional
+	};
+};
 var Emails = class {
 	constructor(mailchannels) {
 		this.mailchannels = mailchannels;
 	}
 	async _sendEmail(options, flags) {
 		let error = null;
-		const { cc, bcc, from, to, html, text, mustaches, dkim } = options;
-		const parsedFrom = parseRecipient(from);
-		if (!parsedFrom || !parsedFrom.email) {
-			error = createError("No sender provided. Use the `from` option to specify a sender");
-			return {
-				success: false,
+		const payload = buildSendPayload(options);
+		if (typeof payload === "string") {
+			error = createError(payload);
+			if (flags.async) return {
 				data: null,
 				error
 			};
-		}
-		const parsedTo = parseArrayRecipients(to);
-		if (!parsedTo || !parsedTo.length) {
-			error = createError("No recipients provided. Use the `to` option to specify at least one recipient");
-			return {
-				success: false,
-				data: null,
-				error
-			};
-		}
-		if (!text && !html) {
-			error = createError("No email content provided");
 			return {
 				success: false,
 				data: null,
 				error
 			};
 		}
-		const content = [];
-		const template_type = mustaches ? "mustache" : void 0;
-		if (text) content.push({
-			type: "text/plain",
-			value: text,
-			template_type
-		});
-		if (html) content.push({
-			type: "text/html",
-			value: html,
-			template_type
-		});
-		const payload = {
-			attachments: options.attachments,
-			campaign_id: options.campaignId,
-			personalizations: [{
-				bcc: parseArrayRecipients(bcc),
-				cc: parseArrayRecipients(cc),
-				to: parsedTo,
-				dkim_domain: dkim?.domain || void 0,
-				dkim_private_key: dkim?.privateKey ? stripPemHeaders(dkim.privateKey) : void 0,
-				dkim_selector: dkim?.selector || void 0,
-				dynamic_template_data: options.mustaches
-			}],
-			headers: options.headers,
-			reply_to: parseRecipient(options.replyTo),
-			envelope_from: parseRecipient(options.envelopeFrom),
-			from: parsedFrom,
-			subject: options.subject,
-			content,
-			tracking_settings: options.tracking ? {
-				click_tracking: options.tracking.click ? { enable: options.tracking.click } : void 0,
-				open_tracking: options.tracking.open ? { enable: options.tracking.open } : void 0
-			} : void 0,
-			transactional: options.transactional
-		};
 		const endpoint = flags.async ? "/tx/v1/send-async" : "/tx/v1/send";
 		const response = await this.mailchannels.post(endpoint, {
 			query: { "dry-run": flags.dryRun },
@@ -271,8 +373,23 @@ var Emails = class {
 	async checkDomain(options) {
 		let error = null;
 		const { dkim, domain, senderId } = options;
+		const dkimOptions = dkim ? Array.isArray(dkim) ? dkim : [dkim] : void 0;
+		if (dkimOptions && dkimOptions.length > 10) {
+			error = createError("A maximum of 10 DKIM settings can be provided.");
+			return {
+				data: null,
+				error
+			};
+		}
+		if (dkimOptions?.find(({ privateKey, selector }) => privateKey && !selector)) {
+			error = createError("DKIM settings with a privateKey must also include a selector.");
+			return {
+				data: null,
+				error
+			};
+		}
 		const payload = {
-			dkim_settings: (dkim ? Array.isArray(dkim) ? dkim : [dkim] : void 0)?.map(({ domain, privateKey, selector }) => ({
+			dkim_settings: dkimOptions?.map(({ domain, privateKey, selector }) => ({
 				dkim_domain: domain,
 				dkim_private_key: privateKey ? stripPemHeaders(privateKey) : void 0,
 				dkim_selector: selector
@@ -344,19 +461,7 @@ var Emails = class {
 			error
 		};
 		return {
-			data: clean({
-				algorithm: response.algorithm,
-				createdAt: response.created_at,
-				dnsRecords: response.dkim_dns_records,
-				domain: response.domain,
-				gracePeriodExpiresAt: response.gracePeriodExpiresAt,
-				length: response.key_length,
-				publicKey: response.public_key,
-				retiresAt: response.retiresAt,
-				selector: response.selector,
-				status: response.status,
-				statusModifiedAt: response.status_modified_at
-			}),
+			data: clean(mapDkimKey(response)),
 			error: null
 		};
 	}
@@ -398,19 +503,7 @@ var Emails = class {
 			error
 		};
 		return {
-			data: clean(response.keys.map((key) => ({
-				algorithm: key.algorithm,
-				createdAt: key.created_at,
-				dnsRecords: key.dkim_dns_records,
-				domain: key.domain,
-				gracePeriodExpiresAt: key.gracePeriodExpiresAt,
-				length: key.key_length,
-				publicKey: key.public_key,
-				retiresAt: key.retiresAt,
-				selector: key.selector,
-				status: key.status,
-				statusModifiedAt: key.status_modified_at
-			}))),
+			data: clean(response.keys.map(mapDkimKey)),
 			error: null
 		};
 	}
@@ -476,32 +569,8 @@ var Emails = class {
 		};
 		return {
 			data: clean({
-				new: {
-					algorithm: response.new_key.algorithm,
-					createdAt: response.new_key.created_at,
-					dnsRecords: response.new_key.dkim_dns_records,
-					domain: response.new_key.domain,
-					gracePeriodExpiresAt: response.new_key.gracePeriodExpiresAt,
-					length: response.new_key.key_length,
-					publicKey: response.new_key.public_key,
-					retiresAt: response.new_key.retiresAt,
-					selector: response.new_key.selector,
-					status: response.new_key.status,
-					statusModifiedAt: response.new_key.status_modified_at
-				},
-				rotated: {
-					algorithm: response.rotated_key.algorithm,
-					createdAt: response.rotated_key.created_at,
-					dnsRecords: response.rotated_key.dkim_dns_records,
-					domain: response.rotated_key.domain,
-					gracePeriodExpiresAt: response.rotated_key.gracePeriodExpiresAt,
-					length: response.rotated_key.key_length,
-					publicKey: response.rotated_key.public_key,
-					retiresAt: response.rotated_key.retiresAt,
-					selector: response.rotated_key.selector,
-					status: response.rotated_key.status,
-					statusModifiedAt: response.rotated_key.status_modified_at
-				}
+				new: mapDkimKey(response.new_key),
+				rotated: mapDkimKey(response.rotated_key)
 			}),
 			error: null
 		};
@@ -710,6 +779,35 @@ var Webhooks = class Webhooks {
 			data: null,
 			error
 		};
+		if (options?.statuses && options.statuses.length > 6) return {
+			data: null,
+			error: createError("A maximum of 6 status filters can be provided.")
+		};
+		if (options?.statuses && new Set(options.statuses).size !== options.statuses.length) return {
+			data: null,
+			error: createError("Status filters must be unique.")
+		};
+		if (options?.createdAfter && Number.isNaN(Date.parse(options.createdAfter))) return {
+			data: null,
+			error: createError("createdAfter must be a valid date string.")
+		};
+		if (options?.createdBefore && Number.isNaN(Date.parse(options.createdBefore))) return {
+			data: null,
+			error: createError("createdBefore must be a valid date string.")
+		};
+		if (options?.createdAfter && options?.createdBefore) {
+			const createdAfter = Date.parse(options.createdAfter);
+			const createdBefore = Date.parse(options.createdBefore);
+			const maxRangeMs = 744 * 60 * 60 * 1e3;
+			if (createdBefore <= createdAfter) return {
+				data: null,
+				error: createError("createdBefore must be later than createdAfter.")
+			};
+			if (createdBefore - createdAfter > maxRangeMs) return {
+				data: null,
+				error: createError("The time range between createdAfter and createdBefore must not exceed 31 days.")
+			};
+		}
 		const response = await this.mailchannels.get("/tx/v1/webhook-batch", {
 			query: {
 				created_after: options?.createdAfter,
@@ -2172,8 +2270,8 @@ var MailChannels = class extends MailChannelsClient {
 	lists = new Lists(this);
 	users = new Users(this);
 	service = new Service(this);
-	constructor(key) {
-		super(key);
+	constructor(key, options) {
+		super(key, options);
 	}
 };
 export { Domains, Emails, Lists, MailChannels, MailChannelsClient, Metrics, Service, SubAccounts, Suppressions, Users, Webhooks };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mailchannels-sdk",
-  "version": "0.7.6",
+  "version": "0.7.7",
   "description": "Node.js SDK to integrate MailChannels API into your JavaScript or TypeScript server-side applications.",
   "type": "module",
   "license": "MIT",
@@ -40,21 +40,23 @@
     "@stylistic/eslint-plugin": "^5.10.0",
     "@types/markdown-it": "^14.1.2",
     "@types/node": "^25.5.2",
-    "@vitest/coverage-v8": "^4.1.2",
+    "@vitest/coverage-v8": "^4.1.3",
     "changelogen": "^0.6.2",
     "jiti": "^2.6.1",
     "obuild": "^0.4.33",
-    "oxlint": "^1.58.0",
+    "oxlint": "^1.59.0",
     "scule": "^1.3.0",
     "typescript": "^6.0.2",
     "vitepress": "^2.0.0-alpha.17",
     "vitepress-plugin-group-icons": "^1.7.3",
     "vitepress-plugin-llms": "^1.12.0",
-    "vitest": "^4.1.2"
+    "vitest": "^4.1.3"
   },
   "scripts": {
     "build": "obuild",
+    "parity:fixtures": "node scripts/generate-parity-fixtures.mjs",
     "release": "pnpm lint && pnpm test && pnpm build && changelogen --release && git push --follow-tags",
+    "simulate:email-api": "node scripts/email-api-simulator.mjs",
     "lint": "oxlint",
     "lint:fix": "oxlint --fix",
     "test": "vitest run --reporter=verbose --coverage",