mailchannels-sdk 1.1.0 → 1.2.0

package/.agents/skills/mailchannels-js/resources/custom-tracking-domains.md

@@ -0,0 +1,83 @@
+# Custom Tracking Domains
+
+Register your own hostname for click tracking, open tracking, or unsubscribe
+links instead of MailChannels' shared domains. Once a domain is `active`,
+select it by `name` via `customDomainName` on the send payload — see
+[sending.md](sending.md#custom-tracking-domains).
+
+## Register A Domain
+
+```ts
+import { MailChannels } from 'mailchannels-sdk'
+
+const mc = new MailChannels('YOUR-API-KEY')
+
+const { data, error } = await mc.domains.customTracking.create(
+  'newsletter-clicks',     // label used at send time, ^[a-z0-9-]+$, max 64
+  'click.example.com',
+  'click'                 // click | open | unsubscribe
+)
+```
+
+Before this can complete, `hostname` needs a CNAME record pointing to
+`links.mailchannels.net`.
+
+## DNS Verification Is A Two-Step, Non-Error Flow
+
+`create()` and `update()` (when re-activating a disabled domain) return one
+of two shapes in `data` — both are 2xx responses, not errors:
+
+- **Registered**: `dnsSetupRequired: false` with `name`, `hostname`, `scope`,
+  `status`, `createdAt` are all present..
+- **Pending**: `dnsSetupRequired: true` with `token`, `txtRecordName`,
+  `txtRecordValue`, `instructions` is present (a CNAME-only failure can omit the TXT
+  fields; a fresh registration includes all of them).
+
+Add the TXT record alongside the CNAME, wait for propagation, then call
+`create()` again with the same `name`/`hostname`/`scope`.
+
+If DNS still isn't in place on retry, MailChannels responds `422` instead of
+`202` — that's a real error status, so the SDK returns an `error` object.
+The same pending-verification body is on `error.response`:
+
+```ts
+const { data, error } = await mc.domains.customTracking.create(
+  'newsletter-clicks',
+  'click.example.com',
+  'click'
+)
+
+if (error) {
+  if (error.statusCode === 422 && error.response) {
+    console.log(error.response.instructions)
+  }
+  return;
+}
+```
+
+## List, Update, Delete
+
+```ts
+// List
+const { data: listData, error: listError } = await mc.domains.customTracking.list({
+  scope: 'click',       // optional filter
+  status: 'active',     // optional filter: active | disabled
+  limit: 100,
+  offset: 0
+})
+
+// Update
+const { data: updateData, error: updateError } = await mc.domains.customTracking.update(
+  'click.example.com',
+  'click',
+  { status: 'disabled' }   // or { name: 'new-label' } to rename
+)
+
+// Delete
+const { success, error: deleteError } = await mc.domains.customTracking.delete('click.example.com', 'click')
+```
+
+Deleting a domain takes effect immediately — tracking links and unsubscribe
+URLs already sent using that domain stop working right away. Re-activating a
+domain whose DNS verification has since lapsed goes through the same
+pending-result flow as `create()`.

package/.agents/skills/mailchannels-js/resources/error-handling.md

@@ -23,6 +23,7 @@ if (error) {
   // error.message    — human-readable description
   // error.type       — stable string identifier (see table below)
   // error.statusCode — HTTP status code, or null for non-HTTP errors
+  // error.response   — Response body (Object) for 4xx/5xx errors
   console.error(error.message, error.type, error.statusCode)
   return
 }

package/.agents/skills/mailchannels-js/resources/metrics-and-usage.md

@@ -57,11 +57,12 @@ for (const bucket of data?.buckets.processed ?? []) {
 
 #### Engagement Buckets
 
-`data.buckets` has `open`, `click`, `openTrackingDelivered`, `clickTrackingDelivered`.
+`data.buckets` has `open`, `click`, `uniqueOpen`, `uniqueClick`, `openTrackingDelivered`,
+`clickTrackingDelivered`, `uniqueOpenTrackingDelivered`, `uniqueClickTrackingDelivered`.
 
 #### Performance Buckets
 
-`data.buckets` has `processed`, `delivered`, `bounced`.
+`data.buckets` has `processed`, `delivered`, `bounced`, `complained`.
 
 #### Recipient Behaviour Buckets
 

package/.agents/skills/mailchannels-js/resources/sending.md

@@ -193,3 +193,29 @@ const { data, error } = await mc.emails.queue({
 ```
 
 Open and click tracking require a subscription that supports them.
+
+### Custom Tracking Domains
+
+Pass `customDomainName` on the `tracking` field (or on `unsubscribe`) to route those
+links through a domain you registered instead of the shared MailChannels domain.
+The name must match an **active** custom tracking domain registered for that
+scope — see [custom-tracking-domains](custom-tracking-domains.md) for
+registration and DNS verification.
+
+```ts
+const { data, error } = await mc.emails.queue({
+  from: 'sender@example.com',
+  to: 'recipient@example.net',
+  subject: 'Tracked with a custom domain',
+  html: "<p>Hello <a href='https://example.com'>click here</a></p>",
+  tracking: {
+    click: {
+      enable: true,
+      customDomainName: 'newsletter-clicks'
+    }
+  },
+  unsubscribe: {
+    customDomainName: 'newsletter-unsubscribe'
+  }
+})
+```

package/.agents/skills/mailchannels-js/resources/sub-accounts.md

@@ -67,7 +67,7 @@ if  (createPwdErr) { /*...*/ }
 const { data: passwords, error: listPwdErr } = await mc.subAccounts.smtpPasswords.list('clienta')
 if (listPwdErr) { /*...*/ }
 
-const { error: deletePwdErr } = await mc.subAccounts.smtpPasswordss.delete('clienta', storedPasswordId)
+const { error: deletePwdErr } = await mc.subAccounts.smtpPasswords.delete('clienta', storedPasswordId)
 if (deletePwdErr) { /*...*/ }
 ```
 

package/README.md

@@ -9,12 +9,12 @@
 [![TypeScript][typescript-src]][typescript-href]
 [![Node.js][node-src]][node-href]
 
-> Built and tested against Email API `1.0.0`
+> Built and tested against Email API `1.4.0`
 
-Node.js SDK to integrate [MailChannels Email API](https://docs.mailchannels.net/email-api) into your JavaScript or TypeScript server-side applications.
+Node.js SDK to integrate [MailChannels Email API](https://docs.mailchannels.com/email-api) into your JavaScript or TypeScript server-side applications.
 
 <!-- #region overview -->
-This library provides a simple way to interact with the [MailChannels Email API](https://docs.mailchannels.net/email-api). It is written in TypeScript and can be used in both JavaScript and TypeScript projects and in different runtimes.
+This library provides a simple way to interact with the [MailChannels Email API](https://docs.mailchannels.com/email-api). It is written in TypeScript and can be used in both JavaScript and TypeScript projects and in different runtimes.
 <!-- #endregion overview -->
 
 - [✨ Release Notes](https://bitbucket.org/mailchannels/mailchannels-email-api-sdk-js/src/HEAD/CHANGELOG.md)
@@ -35,7 +35,7 @@ This library provides a simple way to interact with the [MailChannels Email API]
 ## <a name="features">🚀 Features</a>
 
 <!-- #region features -->
-This SDK fully supports all features and operations available in the [MailChannels Email API](https://docs.mailchannels.net/email-api). It is actively maintained to ensure compatibility and to quickly add support for new API features as they are released.
+This SDK fully supports all features and operations available in the [MailChannels Email API](https://docs.mailchannels.com/email-api). It is actively maintained to ensure compatibility and to quickly add support for new API features as they are released.
 
 Some of the things you can do with the SDK:
 
@@ -169,6 +169,7 @@ const { data, error } = await mailchannels.emails.send({
 - Email sends and async sends
 - Domain checks
 - DKIM key create, list, rotate, and update
+- Custom tracking domain create, list, update, and delete
 - 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
@@ -179,6 +180,7 @@ const { data, error } = await mailchannels.emails.send({
 - 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
+- Custom tracking domain verification is simulated, but the simulator does not yet check DNS records
 
 The next planned expansion is outbound webhook delivery so client applications can test webhook ingestion flows against the simulator as well.
 <!-- #endregion simulator -->

package/dist/_chunks/simulator.mjs

@@ -55,6 +55,7 @@ const createMetricsBuckets = (count) => [{
 const createAccountState = (apiKey) => ({
 	apiKey,
 	customerHandle: createId("customer"),
+	customTrackingDomains: [],
 	dkimKeysByDomain: /* @__PURE__ */ new Map(),
 	messages: [],
 	subAccounts: /* @__PURE__ */ new Map(),
@@ -101,6 +102,16 @@ const createDkimKey = (domain, selector, overrides = {}) => {
 	};
 };
 const listDkimKeys = (account, domain) => account.dkimKeysByDomain.get(domain) || [];
+const createCustomTrackingDomain = ({ hostname, name, scope, status = "active" }) => ({
+	created_at: currentTimestamp(),
+	hostname,
+	name,
+	scope,
+	status
+});
+const findCustomTrackingDomain = (account, hostname, scope) => {
+	return account.customTrackingDomains.find((domain) => domain.hostname === hostname && domain.scope === scope);
+};
 const recordWebhookBatch = (account, webhook, eventCount, status = "2xx_response", statusCode = 200) => {
 	account.webhookBatches.unshift({
 		batch_id: account.nextIds.batch++,
@@ -125,6 +136,7 @@ const collectMessages = (account, filters = {}) => {
 };
 const summarizeMessages = (messages) => ({
 	bounced: messages.reduce((total, message) => total + message.bounced, 0),
+	complained: messages.reduce((total, message) => total + message.complained, 0),
 	click: messages.reduce((total, message) => total + message.click, 0),
 	clickTrackingDelivered: messages.reduce((total, message) => total + message.clickTrackingDelivered, 0),
 	delivered: messages.reduce((total, message) => total + message.delivered, 0),
@@ -198,6 +210,7 @@ const createEmailApiHandler = ({ logRequests = true } = {}) => {
 					account.messages.push({
 						bounced: 0,
 						campaignId: body?.campaign_id || "uncategorized",
+						complained: 0,
 						click: body?.tracking_settings?.click_tracking?.enable ? 1 : 0,
 						clickTrackingDelivered: body?.tracking_settings?.click_tracking?.enable ? 1 : 0,
 						delivered: 1,
@@ -240,11 +253,12 @@ const createEmailApiHandler = ({ logRequests = true } = {}) => {
 			}
 			if (method === "POST" && url.pathname === "/tx/v1/check-domain") {
 				const domain = body?.domain || "example.com";
+				const dkimSettings = body?.dkim_settings?.length ? body.dkim_settings : listDkimKeys(account, domain).map((key) => ({
+					dkim_domain: key.domain,
+					dkim_selector: key.selector
+				}));
 				sendJson(response, 200, { check_results: {
-					dkim: (body?.dkim_settings?.length ? body.dkim_settings : listDkimKeys(account, domain).map((key) => ({
-						dkim_domain: key.domain,
-						dkim_selector: key.selector
-					}))).map((setting) => ({
+					dkim: dkimSettings.map((setting) => ({
 						dkim_domain: setting.dkim_domain || domain,
 						dkim_key_status: setting.dkim_private_key ? "provided" : listDkimKeys(account, setting.dkim_domain || domain).find((key) => key.selector === setting.dkim_selector)?.status || "active",
 						dkim_selector: setting.dkim_selector || "default",
@@ -321,6 +335,71 @@ const createEmailApiHandler = ({ logRequests = true } = {}) => {
 				sendNoContent(response);
 				return;
 			}
+			if (url.pathname === "/tx/v1/custom-tracking-domains") {
+				if (method === "POST") {
+					const { hostname, name, scope } = body || {};
+					if (!hostname || !name || !scope) {
+						sendJson(response, 400, { error: "Invalid request body." });
+						return;
+					}
+					const hasDuplicateName = account.customTrackingDomains.some((domain) => domain.name === name);
+					const hasDuplicateHostnameAndScope = Boolean(findCustomTrackingDomain(account, hostname, scope));
+					if (hasDuplicateName || hasDuplicateHostnameAndScope) {
+						sendJson(response, 409, { error: "Custom tracking domain already exists." });
+						return;
+					}
+					const domain = createCustomTrackingDomain({
+						hostname,
+						name,
+						scope
+					});
+					account.customTrackingDomains.push(domain);
+					sendJson(response, 201, clone(domain));
+					return;
+				}
+				if (method === "GET") {
+					const name = url.searchParams.get("name");
+					const status = url.searchParams.get("status");
+					const scope = url.searchParams.get("scope");
+					const offset = Number(url.searchParams.get("offset") || "0");
+					const limit = Number(url.searchParams.get("limit") || "100");
+					let domains = account.customTrackingDomains;
+					if (name) domains = domains.filter((domain) => domain.name === name);
+					if (status) domains = domains.filter((domain) => domain.status === status);
+					if (scope) domains = domains.filter((domain) => domain.scope === scope);
+					sendJson(response, 200, {
+						custom_tracking_domains: clone(domains.slice(offset, offset + limit)),
+						total: domains.length
+					});
+					return;
+				}
+			}
+			const customTrackingDomainMatch = url.pathname.match(/^\/tx\/v1\/custom-tracking-domains\/([^/]+)\/([^/]+)$/);
+			if (customTrackingDomainMatch) {
+				const [, hostname, scope] = customTrackingDomainMatch;
+				const targetDomain = findCustomTrackingDomain(account, hostname, scope);
+				if (!targetDomain) {
+					sendJson(response, 404, { error: `Custom tracking domain for hostname '${hostname}' and scope '${scope}' not found.` });
+					return;
+				}
+				if (method === "PATCH") {
+					if (body?.name) {
+						if (account.customTrackingDomains.some((domain) => domain !== targetDomain && domain.name === body.name)) {
+							sendJson(response, 409, { error: "Name already used by another domain." });
+							return;
+						}
+						targetDomain.name = body.name;
+					}
+					if (body?.status) targetDomain.status = body.status;
+					sendJson(response, 200, clone(targetDomain));
+					return;
+				}
+				if (method === "DELETE") {
+					account.customTrackingDomains = account.customTrackingDomains.filter((domain) => domain !== targetDomain);
+					sendNoContent(response);
+					return;
+				}
+			}
 			if (url.pathname === "/tx/v1/webhook" && method === "POST") {
 				const endpoint = url.searchParams.get("endpoint");
 				if (!endpoint) {
@@ -360,19 +439,20 @@ const createEmailApiHandler = ({ logRequests = true } = {}) => {
 					sendJson(response, 404, { error: "No webhooks found for the account." });
 					return;
 				}
+				const results = Array.from(account.webhooks).map((webhook) => {
+					recordWebhookBatch(account, webhook, 1);
+					return {
+						result: "passed",
+						webhook,
+						response: {
+							body: "simulated validation ok",
+							status: 200
+						}
+					};
+				});
 				sendJson(response, 200, {
 					all_passed: true,
-					results: Array.from(account.webhooks).map((webhook) => {
-						recordWebhookBatch(account, webhook, 1);
-						return {
-							result: "passed",
-							webhook,
-							response: {
-								body: "simulated validation ok",
-								status: 200
-							}
-						};
-					})
+					results
 				});
 				return;
 			}
@@ -383,7 +463,7 @@ const createEmailApiHandler = ({ logRequests = true } = {}) => {
 				const webhook = url.searchParams.get("webhook");
 				const limit = Number(url.searchParams.get("limit") || "500");
 				const offset = Number(url.searchParams.get("offset") || "0");
-				sendJson(response, 200, { webhook_batches: account.webhookBatches.filter((batch) => {
+				const batches = account.webhookBatches.filter((batch) => {
 					if (createdAfter && batch.created_at < createdAfter) return false;
 					if (createdBefore && batch.created_at >= createdBefore) return false;
 					if (webhook && batch.webhook !== webhook) return false;
@@ -391,7 +471,8 @@ const createEmailApiHandler = ({ logRequests = true } = {}) => {
 						if (!statuses.map((status) => `${status}_response`.replace("no_response_response", "no_response")).includes(batch.status)) return false;
 					}
 					return true;
-				}).slice(offset, offset + limit) });
+				});
+				sendJson(response, 200, { webhook_batches: batches.slice(offset, offset + limit) });
 				return;
 			}
 			const webhookBatchResendMatch = url.pathname.match(/^\/tx\/v1\/webhook-batch\/(\d+)\/resend$/);
@@ -528,7 +609,8 @@ const createEmailApiHandler = ({ logRequests = true } = {}) => {
 				}
 			}
 			if (url.pathname === "/tx/v1/metrics/engagement" && method === "GET") {
-				const summary = summarizeMessages(collectMessages(account, { campaignId: url.searchParams.get("campaign_id") || void 0 }));
+				const messages = collectMessages(account, { campaignId: url.searchParams.get("campaign_id") || void 0 });
+				const summary = summarizeMessages(messages);
 				sendJson(response, 200, {
 					buckets: {
 						click: createMetricsBuckets(summary.click),
@@ -546,11 +628,14 @@ const createEmailApiHandler = ({ logRequests = true } = {}) => {
 				return;
 			}
 			if (url.pathname === "/tx/v1/metrics/performance" && method === "GET") {
-				const summary = summarizeMessages(collectMessages(account, { campaignId: url.searchParams.get("campaign_id") || void 0 }));
+				const messages = collectMessages(account, { campaignId: url.searchParams.get("campaign_id") || void 0 });
+				const summary = summarizeMessages(messages);
 				sendJson(response, 200, {
 					bounced: summary.bounced,
+					complained: summary.complained,
 					buckets: {
 						bounced: createMetricsBuckets(summary.bounced),
+						complained: createMetricsBuckets(summary.complained),
 						delivered: createMetricsBuckets(summary.delivered),
 						processed: createMetricsBuckets(summary.processed)
 					},
@@ -562,7 +647,8 @@ const createEmailApiHandler = ({ logRequests = true } = {}) => {
 				return;
 			}
 			if (url.pathname === "/tx/v1/metrics/recipient-behaviour" && method === "GET") {
-				const summary = summarizeMessages(collectMessages(account, { campaignId: url.searchParams.get("campaign_id") || void 0 }));
+				const messages = collectMessages(account, { campaignId: url.searchParams.get("campaign_id") || void 0 });
+				const summary = summarizeMessages(messages);
 				sendJson(response, 200, {
 					buckets: {
 						unsubscribe_delivered: createMetricsBuckets(summary.unsubscribeDelivered),
@@ -576,7 +662,8 @@ const createEmailApiHandler = ({ logRequests = true } = {}) => {
 				return;
 			}
 			if (url.pathname === "/tx/v1/metrics/volume" && method === "GET") {
-				const summary = summarizeMessages(collectMessages(account, { campaignId: url.searchParams.get("campaign_id") || void 0 }));
+				const messages = collectMessages(account, { campaignId: url.searchParams.get("campaign_id") || void 0 });
+				const summary = summarizeMessages(messages);
 				sendJson(response, 200, {
 					buckets: {
 						delivered: createMetricsBuckets(summary.delivered),
@@ -678,7 +765,8 @@ const createEmailApiHandler = ({ logRequests = true } = {}) => {
 			}
 			notFound(response);
 		} catch (error) {
-			sendText(response, 500, error instanceof Error ? error.message : "Simulator error");
+			const message = error instanceof Error ? error.message : "Simulator error";
+			sendText(response, 500, message);
 		}
 	};
 	return {

package/dist/mailchannels.d.mts

@@ -62,6 +62,11 @@ interface ErrorResponse {
    * This field is intended for diagnostic use only and should not be relied upon.
    */
   type: ErrorType;
+  /**
+   * An object containing the response, if available.
+   * This field may be `null` if no response is available or if the error is not related to an HTTP request or if the response is not a JSON object.
+   */
+  response: Record<string, unknown> | null;
 }
 interface SuccessResponse {
   /**
@@ -129,6 +134,12 @@ interface EmailsSendTracking {
    * Track when a recipient clicks a link in your email.
    */
   click?: {
+    /**
+     * The name of a configured active click tracking domain.
+     * When specified, click tracking links will use this domain instead of the default MailChannels domain.
+     * The domain must be registered in your account and have an active status.
+     */
+    customDomainName?: string;
     /**
      * @default false
      */
@@ -138,6 +149,12 @@ interface EmailsSendTracking {
    * Track when a recipient opens your email. Please note that some email clients may not support open tracking.
    */
   open?: {
+    /**
+     * The name of a configured active open tracking domain.
+     * When specified, the open tracking pixel will use this domain instead of the default MailChannels domain.
+     * The domain must be registered in your account and have an active status.
+     */
+    customDomainName?: string;
     /**
      * @default false
      */
@@ -360,10 +377,21 @@ interface EmailsSendOptionsBase {
   /**
    * Mark these messages as transactional or non-transactional. In order for a message to be marked as non-transactional, it must have exactly one recipient per personalization, and it must be DKIM signed. 400 Bad Request will be returned if there are more than one recipient in any personalization for non-transactional messages. If a message is marked as non-transactional, it changes the sending process as follows:
    *
-   * List-Unsubscribe headers will be added.
+   * List-Unsubscribe and List-Unsubscribe-Post headers will be added, unless you supply your own List-Unsubscribe header, in which case yours is used and neither is added.
    * @default true
    */
   transactional?: boolean;
+  /**
+   * Settings to customize the unsubscribe experience for the message.
+   */
+  unsubscribe?: {
+    /**
+     * The name of a configured active unsubscribe tracking domain.
+     * When specified, unsubscribe links will use this domain instead of the default MailChannels domain.
+     * The domain must be registered in your account and have an active status.
+     */
+    customDomainName?: string;
+  };
 }
 type EmailsSendTargetOptions = {
   personalizations: (Omit<EmailsSendPersonalization, "template"> & {
@@ -697,6 +725,171 @@ declare class DomainsDkim {
    */
   rotate(domain: string, selector: string, options: DomainsDkimRotateOptions): Promise<DomainsDkimRotateResponse>;
 }
+type DomainsCustomTrackingScope = "click" | "open" | "unsubscribe";
+interface DomainsCustomTrackingDomain {
+  /**
+   * The label for this custom tracking domain.
+   */
+  name: string;
+  /**
+   * The registered domain hostname.
+   */
+  hostname: string;
+  /**
+   * The event type this domain handles.
+   */
+  scope: DomainsCustomTrackingScope;
+  /**
+   * Current status of the custom tracking domain.
+   */
+  status: "active" | "disabled";
+  /**
+   * ISO 8601 timestamp when the domain was registered.
+   */
+  createdAt: string;
+}
+interface DomainsCustomTrackingDnsSetupRequired {
+  /**
+   * UUID v4 nonce; also the TXT record value to set. Present only when TXT ownership verification is pending.
+   * @example "550e8400-e29b-41d4-a716-446655440000"
+   */
+  token?: string;
+  /**
+   * Fully-qualified DNS TXT record name to add. Present only when TXT ownership verification is pending.
+   * @example "_mailchannels-verify.click.example.com"
+   */
+  txtRecordName?: string;
+  /**
+   * Value for the DNS TXT record (same as token). Present only when TXT ownership verification is pending.
+   * @example "550e8400-e29b-41d4-a716-446655440000"
+   */
+  txtRecordValue?: string;
+  /**
+   * Human-readable guidance for the DNS records that must be in place before retrying.
+   */
+  instructions?: string;
+}
+type DomainsCustomTrackingWithDnsSetupRequired<T extends 202 | 201 | 200 | undefined = undefined> = T extends undefined ? DomainsCustomTrackingDomain & {
+  dnsSetupRequired: false;
+} | DomainsCustomTrackingDnsSetupRequired & {
+  dnsSetupRequired: true;
+} : T extends 202 ? DomainsCustomTrackingDnsSetupRequired & {
+  dnsSetupRequired: true;
+} : DomainsCustomTrackingDomain & {
+  dnsSetupRequired: false;
+};
+type DomainsCustomTrackingCreateResponse = DataResponse<DomainsCustomTrackingWithDnsSetupRequired>;
+interface DomainsCustomTrackingListOptions {
+  /**
+   * Filter by custom tracking domain label.
+   */
+  name?: string;
+  /**
+   * Filter by status.
+   */
+  status?: "active" | "disabled";
+  /**
+   * Filter by scope.
+   */
+  scope?: DomainsCustomTrackingScope;
+  /**
+   * The maximum number of domains to return. Possible values are `1` to `1000`.
+   * @default 100
+   */
+  limit?: number;
+  /**
+   * The number of domains to skip before returning results. The default is `0`.
+   * @default 0
+   */
+  offset?: number;
+}
+type DomainsCustomTrackingListResponse = DataResponse<{
+  /**
+   * List of custom tracking domains matching the filter criteria.
+   */
+  customTrackingDomains: DomainsCustomTrackingDomain[];
+  /**
+   * Total number of custom tracking domains.
+   */
+  total: number;
+}>;
+interface DomainsCustomTrackingUpdateOptions {
+  /**
+   * New label for this custom tracking domain. Maximum length is `64` characters. Must match the pattern `^[a-z0-9-]+$`.
+   */
+  name?: string;
+  /**
+   * New status. Re-activation requires DNS verification — add the TXT record and CNAME record described in the response body, then retry.
+   */
+  status?: "active" | "disabled";
+}
+type DomainsCustomTrackingUpdateResponse = DataResponse<DomainsCustomTrackingWithDnsSetupRequired>;
+declare class DomainsCustomTracking {
+  private mailchannels;
+  private static readonly SCOPE_VALUES;
+  constructor(mailchannels: MailChannelsClient);
+  /**
+   * Retrieve all custom tracking domains registered under your account.
+   * Optional filters include domain name, status, scope, limit and offset.
+   * @param options - Optional filter options.
+   * @example
+   * ```ts
+   * const mailchannels = new MailChannels('your-api-key')
+   * const { data, error } = await mailchannels.domains.customTracking.list({
+   *   status: 'active'
+   * })
+   * ```
+   */
+  list(options?: DomainsCustomTrackingListOptions): Promise<DomainsCustomTrackingListResponse>;
+  /**
+   * Register a custom branded domain for click tracking, open tracking, or unsubscribe handling. By default, MailChannels uses shared domains for these links. Using a custom domain improves brand consistency by replacing shared domains with your own (e.g., `click.example.com`). Once registered, select the domain at send time using its `name`.
+   *
+   * Before registration completes, two DNS records must be in place:
+   * 1. A TXT record at `_mailchannels-verify.<hostname>` containing the verification token (returned when DNS setup is required).
+   * 2. A CNAME record at `<hostname>` pointing to `links.mailchannels.net`.
+   * @param name - A unique label used to select this domain at message send time. Maximum length is `64` characters. Must match the pattern `^[a-z0-9-]+$`.
+   * @param hostname - The hostname to register as a custom tracking domain (e.g., `click.example.com`).
+   * @param scope - The event type this domain handles.
+   * @example
+   * ```ts
+   * const mailchannels = new MailChannels('your-api-key')
+   * const { data, error } = await mailchannels.domains.customTracking.create(
+   *   'clickdemo',
+   *   'click.example.com',
+   *   'click'
+   * )
+   * ```
+   */
+  create(name: string, hostname: string, scope: DomainsCustomTrackingScope): Promise<DomainsCustomTrackingCreateResponse>;
+  /**
+   * Update an existing custom tracking domain by its hostname and scope. Supports updating the custom tracking domain's name or toggling its active status.
+   * @param hostname - The hostname of the custom tracking domain to update.
+   * @param scope - The scope of the custom tracking domain to update.
+   * @param options - The options for updating the custom tracking domain.
+   * @example
+   * ```ts
+   * const mailchannels = new MailChannels('your-api-key')
+   * const { data, error } = await mailchannels.domains.customTracking.update('click.example.com', 'click', {
+   *   name: 'newclickname',
+   *   status: 'active'
+   * })
+   * ```
+   */
+  update(hostname: string, scope: DomainsCustomTrackingScope, options: DomainsCustomTrackingUpdateOptions): Promise<DomainsCustomTrackingUpdateResponse>;
+  /**
+   * Permanently delete an existing custom tracking domain for the given hostname and scope. The domain can be re-registered if needed.
+   *
+   * WARNING: Any tracking links or unsubscribe URLs in previously sent emails using this domain will stop working immediately.
+   * @param hostname - The hostname of the custom tracking domain to delete.
+   * @param scope - The scope of the custom tracking domain to delete.
+   * @example
+   * ```ts
+   * const mailchannels = new MailChannels('your-api-key')
+   * const { success, error } = await mailchannels.domains.customTracking.delete('click.example.com', 'click')
+   * ```
+   */
+  delete(hostname: string, scope: DomainsCustomTrackingScope): Promise<SuccessResponse>;
+}
 interface DomainsCheck {
   /**
    * Domain used for DKIM signing.
@@ -792,6 +985,7 @@ type DomainsCheckResponse = DataResponse<{
 declare class Domains {
   protected mailchannels: MailChannelsClient;
   readonly dkim: DomainsDkim;
+  readonly customTracking: DomainsCustomTracking;
   constructor(mailchannels: MailChannelsClient);
   /**
    * Validates a domain's email authentication setup by retrieving its DKIM, SPF, and Domain Lockdown status. This endpoint checks whether the domain is properly configured for secure email delivery.
@@ -1259,25 +1453,74 @@ interface MetricsEngagement {
     clickTrackingDelivered: MetricsBucket[];
     open: MetricsBucket[];
     openTrackingDelivered: MetricsBucket[];
+    uniqueClick?: MetricsBucket[];
+    uniqueClickTrackingDelivered?: MetricsBucket[];
+    uniqueOpen?: MetricsBucket[];
+    uniqueOpenTrackingDelivered?: MetricsBucket[];
   };
+  /**
+   * Count of click events by recipients.
+   */
   click: number;
+  /**
+   * Count of recipients of delivered messages with HTML content that contains tracked click URLs, where click tracking is enabled in the send request.
+   */
   clickTrackingDelivered: number;
+  /**
+   * The end of the time range for retrieving message engagement metrics (exclusive).
+   */
   endTime: string;
+  /**
+   * Count of open events by recipients.
+   */
   open: number;
+  /**
+   * Count of recipients of delivered messages with HTML content where open tracking was enabled in the send request.
+   */
   openTrackingDelivered: number;
+  /**
+   * The beginning of the time range for retrieving message engagement metrics (inclusive).
+   */
   startTime: string;
+  /**
+   * Count of distinct messages that had at least one click event.
+   * Unlike `click`, each message is counted at most once regardless of how many links were clicked or how many times.
+   * Use this to compute click rates without exceeding 100%.
+   */
+  uniqueClick?: number;
+  /**
+   * Count of distinct messages delivered with click tracking enabled (message-level, not recipient-level).
+   * Use as the denominator when computing unique click rates.
+   */
+  uniqueClickTrackingDelivered?: number;
+  /**
+   * Count of distinct messages that had at least one open event.
+   * Unlike `open`, each message is counted at most once regardless of how many times its tracking pixel was fired.
+   * Use this to compute open rates without exceeding 100%.
+   */
+  uniqueOpen?: number;
+  /**
+   * Count of distinct messages delivered with open tracking enabled (message-level, not recipient-level).
+   * Use as the denominator when computing unique open rates.
+   */
+  uniqueOpenTrackingDelivered?: number;
 }
 type MetricsEngagementResponse = DataResponse<MetricsEngagement>;
 interface MetricsPerformance {
   /**
-   * Count of messages bounced during the specified time range.
+   * Count of messages hard-bounced during the specified time range.
    */
   bounced: number;
+  /**
+   * Count of messages complained during the specified time range.
+   */
+  complained: number;
   /**
    * A series of metrics aggregations bucketed by time interval (e.g. hour, day).
    */
   buckets: {
     bounced: MetricsBucket[];
+    complained: MetricsBucket[];
     delivered: MetricsBucket[];
     processed: MetricsBucket[];
   };
@@ -1727,7 +1970,7 @@ declare class Metrics {
    */
   engagement(options?: MetricsOptions): Promise<MetricsEngagementResponse>;
   /**
-   * Retrieve performance metrics for messages sent from your account, including counts of processed, delivered, hard-bounced events. Supports optional filters for time range, and campaign ID.
+   * Retrieve performance metrics for messages sent from your account, including counts of processed, delivered, hard-bounced, and complained events. Supports optional filters for time range, and campaign ID.
    * @param options - Options to filter and customize the performance metrics retrieval.
    * @example
    * ```ts
@@ -1827,4 +2070,4 @@ declare class MailChannels extends MailChannelsClient {
   readonly suppressions: Suppressions;
   constructor(key: string, options?: MailChannelsClientOptions);
 }
-export { Attachment, type DataResponse, Domains, type DomainsCheckOptions, type DomainsCheckResponse, type DomainsCheckVerdict, type DomainsDkimCreateOptions, type DomainsDkimCreateResponse, type DomainsDkimKey, type DomainsDkimKeyStatus, type DomainsDkimListOptions, type DomainsDkimListResponse, type DomainsDkimRotateOptions, type DomainsDkimRotateResponse, type DomainsDkimUpdateStatusOptions, Emails, type EmailsQueueResponse, type EmailsSendAsyncResponse, type EmailsSendAttachment, type EmailsSendContent, type EmailsSendDkim, type EmailsSendOptions, type EmailsSendPersonalization, type EmailsSendRecipient, type EmailsSendRecipientInput, type EmailsSendResponse, type EmailsSendTemplate, type EmailsSendTemplateType, type EmailsSendTemplateValue, type EmailsSendTracking, type ErrorResponse, type ErrorType, MailChannels, MailChannelsClient, type MailChannelsClientOptions, Metrics, type MetricsBucket, type MetricsEngagement, type MetricsEngagementResponse, type MetricsOptions, type MetricsPerformance, type MetricsPerformanceResponse, type MetricsRecipientBehaviour, type MetricsRecipientBehaviourResponse, type MetricsSenders, type MetricsSendersOptions, type MetricsSendersResponse, type MetricsSendersType, type MetricsUsageResponse, type MetricsVolume, type MetricsVolumeResponse, type SubAccount, SubAccounts, type SubAccountsAccount, type SubAccountsApiKey, type SubAccountsApiKeysCreateResponse, type SubAccountsApiKeysListOptions, type SubAccountsApiKeysListResponse, type SubAccountsCreateApiKeyResponse, type SubAccountsCreateResponse, type SubAccountsCreateSmtpPasswordResponse, type SubAccountsLimit, type SubAccountsLimitResponse, type SubAccountsLimitsGetResponse, type SubAccountsLimitsSetOptions, type SubAccountsListApiKeyOptions, type SubAccountsListApiKeyResponse, type SubAccountsListOptions, type SubAccountsListResponse, type SubAccountsListSmtpPasswordResponse, type SubAccountsSmtpPassword, type SubAccountsSmtpPasswordsCreateResponse, type SubAccountsSmtpPasswordsListResponse, type SubAccountsUsage, type SubAccountsUsageResponse, type SuccessResponse, Suppressions, type SuppressionsCreateOptions, type SuppressionsListEntry, type SuppressionsListOptions, type SuppressionsListResponse, type SuppressionsSource, type SuppressionsTypes, type WebhookEvent, type WebhookEventClick, type WebhookEventComplained, type WebhookEventDelivered, type WebhookEventDropped, type WebhookEventHardBounced, type WebhookEventOpen, type WebhookEventProcessed, type WebhookEventSoftBounced, type WebhookEventTest, type WebhookEventType, type WebhookEventUnsubscribed, Webhooks, type WebhooksBatch, type WebhooksBatchResponseStatus, type WebhooksBatchStatus, type WebhooksBatchesOptions, type WebhooksBatchesResponse, type WebhooksListResponse, type WebhooksResendBatch, type WebhooksResendBatchResponse, type WebhooksSigningKeyResponse, type WebhooksValidateResponse, type WebhooksVerifyOptions, type WebhooksVerifyResponse };
+export { Attachment, type DataResponse, Domains, type DomainsCheckOptions, type DomainsCheckResponse, type DomainsCheckVerdict, type DomainsCustomTrackingCreateResponse, type DomainsCustomTrackingDnsSetupRequired, type DomainsCustomTrackingDomain, type DomainsCustomTrackingListOptions, type DomainsCustomTrackingListResponse, type DomainsCustomTrackingScope, type DomainsCustomTrackingUpdateOptions, type DomainsCustomTrackingUpdateResponse, type DomainsCustomTrackingWithDnsSetupRequired, type DomainsDkimCreateOptions, type DomainsDkimCreateResponse, type DomainsDkimKey, type DomainsDkimKeyStatus, type DomainsDkimListOptions, type DomainsDkimListResponse, type DomainsDkimRotateOptions, type DomainsDkimRotateResponse, type DomainsDkimUpdateStatusOptions, Emails, type EmailsQueueResponse, type EmailsSendAsyncResponse, type EmailsSendAttachment, type EmailsSendContent, type EmailsSendDkim, type EmailsSendOptions, type EmailsSendPersonalization, type EmailsSendRecipient, type EmailsSendRecipientInput, type EmailsSendResponse, type EmailsSendTemplate, type EmailsSendTemplateType, type EmailsSendTemplateValue, type EmailsSendTracking, type ErrorResponse, type ErrorType, MailChannels, MailChannelsClient, type MailChannelsClientOptions, Metrics, type MetricsBucket, type MetricsEngagement, type MetricsEngagementResponse, type MetricsOptions, type MetricsPerformance, type MetricsPerformanceResponse, type MetricsRecipientBehaviour, type MetricsRecipientBehaviourResponse, type MetricsSenders, type MetricsSendersOptions, type MetricsSendersResponse, type MetricsSendersType, type MetricsUsageResponse, type MetricsVolume, type MetricsVolumeResponse, type SubAccount, SubAccounts, type SubAccountsAccount, type SubAccountsApiKey, type SubAccountsApiKeysCreateResponse, type SubAccountsApiKeysListOptions, type SubAccountsApiKeysListResponse, type SubAccountsCreateApiKeyResponse, type SubAccountsCreateResponse, type SubAccountsCreateSmtpPasswordResponse, type SubAccountsLimit, type SubAccountsLimitResponse, type SubAccountsLimitsGetResponse, type SubAccountsLimitsSetOptions, type SubAccountsListApiKeyOptions, type SubAccountsListApiKeyResponse, type SubAccountsListOptions, type SubAccountsListResponse, type SubAccountsListSmtpPasswordResponse, type SubAccountsSmtpPassword, type SubAccountsSmtpPasswordsCreateResponse, type SubAccountsSmtpPasswordsListResponse, type SubAccountsUsage, type SubAccountsUsageResponse, type SuccessResponse, Suppressions, type SuppressionsCreateOptions, type SuppressionsListEntry, type SuppressionsListOptions, type SuppressionsListResponse, type SuppressionsSource, type SuppressionsTypes, type WebhookEvent, type WebhookEventClick, type WebhookEventComplained, type WebhookEventDelivered, type WebhookEventDropped, type WebhookEventHardBounced, type WebhookEventOpen, type WebhookEventProcessed, type WebhookEventSoftBounced, type WebhookEventTest, type WebhookEventType, type WebhookEventUnsubscribed, Webhooks, type WebhooksBatch, type WebhooksBatchResponseStatus, type WebhooksBatchStatus, type WebhooksBatchesOptions, type WebhooksBatchesResponse, type WebhooksListResponse, type WebhooksResendBatch, type WebhooksResendBatchResponse, type WebhooksSigningKeyResponse, type WebhooksValidateResponse, type WebhooksVerifyOptions, type WebhooksVerifyResponse };

package/dist/mailchannels.mjs

@@ -2,7 +2,7 @@ import { $fetch } from "ofetch";
 import { subtle } from "node:crypto";
 import { Buffer } from "node:buffer";
 import mime from "mime";
-var version = "1.1.0";
+var version = "1.2.0";
 var MailChannelsClient = class MailChannelsClient {
 	static DEFAULT_BASE_URL = "https://api.mailchannels.net";
 	static DEFAULT_TIMEOUT = 12e4;
@@ -79,21 +79,26 @@ const STATUS_ERROR_TYPE_MAP = {
 	[429]: "rate_limit_error",
 	[500]: "internal_server_error"
 };
-const createError = (message, statusCode = null, type) => {
+const createError = (message, statusCode = null, type, response = null) => {
 	return {
 		message,
 		statusCode,
-		type
+		type,
+		response
 	};
 };
 const getStatusError = (response, errors = {}) => {
 	const statusText = errors[response.status] || "Unknown error.";
 	const payload = response._data ?? response.data;
 	let details;
+	let errorResponse = null;
 	if (typeof payload === "string") details = payload;
-	else if (payload?.message) details = payload.message;
-	else if (Array.isArray(payload?.errors) && payload.errors?.length) details = payload.errors.join(", ");
-	return createError(details ? `${statusText} ${details}` : statusText, response.status ?? null, STATUS_ERROR_TYPE_MAP[response.status] || "api_error");
+	else if (typeof payload === "object" && payload !== null) {
+		if (typeof payload.message === "string") details = payload.message;
+		else if (Array.isArray(payload.errors) && payload.errors.length) details = payload.errors.join(", ");
+		errorResponse = payload;
+	}
+	return createError(details ? `${statusText} ${details}` : statusText, response.status ?? null, STATUS_ERROR_TYPE_MAP[response.status] || "api_error", errorResponse);
 };
 const getResultError = (e, fallback) => {
 	return createError(e instanceof Error ? e.message : fallback, null, "application_error");
@@ -107,6 +112,12 @@ const validatePagination = (pagination = {}) => {
 	if (typeof offset === "number" && offset < 0) return createValidationError("Offset must be greater than or equal to 0.");
 	return null;
 };
+const CUSTOM_TRACKING_NAME_PATTERN = /^[a-z0-9-]+$/;
+const validateCustomTrackingName = (name) => {
+	if (!name || name.length < 1 || name.length > 64) return createValidationError("The custom tracking domain name must be between 1 and 64 characters.");
+	if (!CUSTOM_TRACKING_NAME_PATTERN.test(name)) return createValidationError("The custom tracking domain name must match ^[a-z0-9-]+$");
+	return null;
+};
 const clean = (data) => {
 	if (Array.isArray(data)) {
 		const result = [];
@@ -305,6 +316,18 @@ const buildSendPayload = async (options) => {
 			return getRecipientCount(personalization.to) + getRecipientCount(personalization.cc) + getRecipientCount(personalization.bcc) !== 1;
 		})) return "Non-transactional messages must have exactly one recipient per personalization.";
 	}
+	if (options.tracking?.click?.customDomainName !== void 0) {
+		const clickCustomTrackingNameError = validateCustomTrackingName(options.tracking.click.customDomainName);
+		if (clickCustomTrackingNameError) return `Invalid click tracking: ${clickCustomTrackingNameError.message}`;
+	}
+	if (options.tracking?.open?.customDomainName !== void 0) {
+		const openCustomTrackingNameError = validateCustomTrackingName(options.tracking.open.customDomainName);
+		if (openCustomTrackingNameError) return `Invalid open tracking: ${openCustomTrackingNameError.message}`;
+	}
+	if (options.unsubscribe?.customDomainName !== void 0) {
+		const unsubscribeCustomTrackingNameError = validateCustomTrackingName(options.unsubscribe.customDomainName);
+		if (unsubscribeCustomTrackingNameError) return `Invalid unsubscribe settings: ${unsubscribeCustomTrackingNameError.message}`;
+	}
 	const content = [];
 	const template_type = options.template?.type;
 	if (text) content.push({
@@ -335,11 +358,18 @@ const buildSendPayload = async (options) => {
 		from: parsedFrom,
 		subject: options.subject,
 		content,
-		tracking_settings: options.tracking ? {
-			click_tracking: options.tracking.click ? { enable: options.tracking.click.enable } : void 0,
-			open_tracking: options.tracking.open ? { enable: options.tracking.open.enable } : void 0
-		} : void 0,
-		transactional: options.transactional
+		tracking_settings: options.tracking && {
+			click_tracking: options.tracking.click && {
+				custom_domain_name: options.tracking.click.customDomainName,
+				enable: options.tracking.click.enable
+			},
+			open_tracking: options.tracking.open && {
+				custom_domain_name: options.tracking.open.customDomainName,
+				enable: options.tracking.open.enable
+			}
+		},
+		transactional: options.transactional,
+		unsubscribe_settings: options.unsubscribe && { custom_domain_name: options.unsubscribe.customDomainName }
 	};
 };
 var Emails = class {
@@ -603,12 +633,245 @@ var DomainsDkim = class {
 		};
 	}
 };
+var DomainsCustomTracking = class DomainsCustomTracking {
+	mailchannels;
+	static SCOPE_VALUES = /* @__PURE__ */ new Set([
+		"click",
+		"open",
+		"unsubscribe"
+	]);
+	constructor(mailchannels) {
+		this.mailchannels = mailchannels;
+	}
+	async list(options) {
+		let error = null;
+		error = validatePagination({
+			...options,
+			max: 1e3
+		});
+		if (error) return {
+			data: null,
+			error
+		};
+		const response = await this.mailchannels.get("/tx/v1/custom-tracking-domains", {
+			query: options,
+			onResponseError: async ({ response }) => {
+				error = getStatusError(response, { [400]: "Bad Request." });
+			}
+		}).catch((e) => {
+			error ||= getResultError(e, "Failed to fetch custom tracking domains.");
+			return null;
+		});
+		if (!response) return {
+			data: null,
+			error
+		};
+		return {
+			data: clean({
+				customTrackingDomains: response.custom_tracking_domains.map((d) => ({
+					name: d.name,
+					hostname: d.hostname,
+					scope: d.scope,
+					status: d.status,
+					createdAt: d.created_at
+				})),
+				total: response.total
+			}),
+			error: null
+		};
+	}
+	async create(name, hostname, scope) {
+		let error = null;
+		error = validateCustomTrackingName(name);
+		if (error) return {
+			data: null,
+			error
+		};
+		if (!hostname) {
+			error = createValidationError("Hostname is required.");
+			return {
+				data: null,
+				error
+			};
+		}
+		if (!scope || !DomainsCustomTracking.SCOPE_VALUES.has(scope)) {
+			error = createValidationError("Scope must be one of 'click', 'open', or 'unsubscribe'.");
+			return {
+				data: null,
+				error
+			};
+		}
+		const payload = {
+			name,
+			hostname,
+			scope
+		};
+		let statusCode = null;
+		const response = await this.mailchannels.post("/tx/v1/custom-tracking-domains", {
+			body: payload,
+			onResponse: async ({ response }) => {
+				statusCode = response.status;
+			},
+			onResponseError: async ({ response }) => {
+				error = getStatusError(response, {
+					[400]: "Invalid request body.",
+					[403]: "No permission to register this domain.",
+					[409]: "A domain with the same name already exists, or the hostname and scope combination is already registered.",
+					[422]: "DNS verification incomplete. Either the TXT ownership record has not propagated yet or the hostname CNAME does not point to the required target."
+				});
+			}
+		}).catch((e) => {
+			error ||= getResultError(e, "Failed to create custom tracking domain.");
+			return null;
+		});
+		if (!response) return {
+			data: null,
+			error
+		};
+		if (statusCode === 202) {
+			const dnsSetupRequiredResponse = response;
+			return {
+				data: clean({
+					dnsSetupRequired: true,
+					token: dnsSetupRequiredResponse.token,
+					txtRecordName: dnsSetupRequiredResponse.txt_record_name,
+					txtRecordValue: dnsSetupRequiredResponse.txt_record_value,
+					instructions: dnsSetupRequiredResponse.instructions
+				}),
+				error: null
+			};
+		}
+		const createResponse = response;
+		return {
+			data: clean({
+				dnsSetupRequired: false,
+				name: createResponse.name,
+				hostname: createResponse.hostname,
+				scope: createResponse.scope,
+				status: createResponse.status,
+				createdAt: createResponse.created_at
+			}),
+			error: null
+		};
+	}
+	async update(hostname, scope, options) {
+		let error = null;
+		if (!hostname) {
+			error = createValidationError("Hostname is required.");
+			return {
+				data: null,
+				error
+			};
+		}
+		if (!scope || !DomainsCustomTracking.SCOPE_VALUES.has(scope)) {
+			error = createValidationError("Scope must be one of 'click', 'open', or 'unsubscribe'.");
+			return {
+				data: null,
+				error
+			};
+		}
+		if (options.name !== void 0) {
+			error = validateCustomTrackingName(options.name);
+			if (error) return {
+				data: null,
+				error
+			};
+		}
+		if (options.name === void 0 && options.status === void 0) {
+			error = createValidationError("At least one of 'name' or 'status' must be provided.");
+			return {
+				data: null,
+				error
+			};
+		}
+		const payload = {
+			name: options.name,
+			status: options.status
+		};
+		let statusCode = null;
+		const response = await this.mailchannels.patch(`/tx/v1/custom-tracking-domains/${encodeURIComponent(hostname)}/${encodeURIComponent(scope)}`, {
+			body: payload,
+			onResponse: async ({ response }) => {
+				statusCode = response.status;
+			},
+			onResponseError: async ({ response }) => {
+				error = getStatusError(response, {
+					[400]: "Bad Request.",
+					[403]: "No permission to update this domain.",
+					[404]: `Custom tracking domain for hostname '${hostname}' and scope '${scope}' not found.`,
+					[409]: "Name already used by another domain.",
+					[422]: "DNS verification incomplete. Either the TXT ownership record has not propagated yet or the hostname CNAME does not point to the required target."
+				});
+			}
+		}).catch((e) => {
+			error ||= getResultError(e, "Failed to update custom tracking domain.");
+			return null;
+		});
+		if (!response) return {
+			data: null,
+			error
+		};
+		if (statusCode === 202) {
+			const dnsSetupRequiredResponse = response;
+			return {
+				data: clean({
+					dnsSetupRequired: true,
+					token: dnsSetupRequiredResponse.token,
+					txtRecordName: dnsSetupRequiredResponse.txt_record_name,
+					txtRecordValue: dnsSetupRequiredResponse.txt_record_value,
+					instructions: dnsSetupRequiredResponse.instructions
+				}),
+				error: null
+			};
+		}
+		const updateResponse = response;
+		return {
+			data: clean({
+				dnsSetupRequired: false,
+				name: updateResponse.name,
+				hostname: updateResponse.hostname,
+				scope: updateResponse.scope,
+				status: updateResponse.status,
+				createdAt: updateResponse.created_at
+			}),
+			error: null
+		};
+	}
+	async delete(hostname, scope) {
+		let error = null;
+		if (!hostname) {
+			error = createValidationError("Hostname is required.");
+			return {
+				success: false,
+				error
+			};
+		}
+		if (!scope || !DomainsCustomTracking.SCOPE_VALUES.has(scope)) {
+			error = createValidationError("Scope must be one of 'click', 'open', or 'unsubscribe'.");
+			return {
+				success: false,
+				error
+			};
+		}
+		await this.mailchannels.delete(`/tx/v1/custom-tracking-domains/${encodeURIComponent(hostname)}/${encodeURIComponent(scope)}`, { onResponseError: async ({ response }) => {
+			error = getStatusError(response, { [400]: "Invalid hostname or scope value" });
+		} }).catch((e) => {
+			error ||= getResultError(e, "Failed to delete custom tracking domain.");
+		});
+		return {
+			success: !error,
+			error
+		};
+	}
+};
 var Domains = class {
 	mailchannels;
 	dkim;
+	customTracking;
 	constructor(mailchannels) {
 		this.mailchannels = mailchannels;
 		this.dkim = new DomainsDkim(mailchannels);
+		this.customTracking = new DomainsCustomTracking(mailchannels);
 	}
 	async check(domain, options) {
 		let error = null;
@@ -1558,14 +1821,22 @@ var Metrics = class {
 					click: response.buckets.click.map(mapBucket),
 					clickTrackingDelivered: response.buckets.click_tracking_delivered.map(mapBucket),
 					open: response.buckets.open.map(mapBucket),
-					openTrackingDelivered: response.buckets.open_tracking_delivered.map(mapBucket)
+					openTrackingDelivered: response.buckets.open_tracking_delivered.map(mapBucket),
+					uniqueClick: response.buckets.unique_click?.map(mapBucket),
+					uniqueClickTrackingDelivered: response.buckets.unique_click_tracking_delivered?.map(mapBucket),
+					uniqueOpen: response.buckets.unique_open?.map(mapBucket),
+					uniqueOpenTrackingDelivered: response.buckets.unique_open_tracking_delivered?.map(mapBucket)
 				},
 				click: response.click,
 				clickTrackingDelivered: response.click_tracking_delivered,
 				endTime: response.end_time,
 				open: response.open,
 				openTrackingDelivered: response.open_tracking_delivered,
-				startTime: response.start_time
+				startTime: response.start_time,
+				uniqueClick: response.unique_click,
+				uniqueClickTrackingDelivered: response.unique_click_tracking_delivered,
+				uniqueOpen: response.unique_open,
+				uniqueOpenTrackingDelivered: response.unique_open_tracking_delivered
 			}),
 			error: null
 		};
@@ -1601,8 +1872,10 @@ var Metrics = class {
 		return {
 			data: clean({
 				bounced: response.bounced,
+				complained: response.complained,
 				buckets: {
 					bounced: response.buckets.bounced.map(mapBucket),
+					complained: response.buckets.complained.map(mapBucket),
 					delivered: response.buckets.delivered.map(mapBucket),
 					processed: response.buckets.processed.map(mapBucket)
 				},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mailchannels-sdk",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Node.js SDK to integrate MailChannels Email API into your JavaScript or TypeScript server-side applications.",
   "type": "module",
   "license": "MIT",
@@ -43,17 +43,17 @@
   "devDependencies": {
     "@stylistic/eslint-plugin": "^5.10.0",
     "@types/markdown-it": "^14.1.2",
-    "@types/node": "^25.9.3",
-    "@vitest/coverage-v8": "^4.1.9",
+    "@types/node": "^26.1.1",
+    "@vitest/coverage-v8": "^4.1.10",
     "changelogen": "^0.6.2",
-    "obuild": "^0.4.36",
-    "oxlint": "^1.70.0",
+    "obuild": "^0.4.37",
+    "oxlint": "^1.73.0",
     "scule": "^1.3.0",
     "typescript": "^6.0.3",
-    "vitepress": "^2.0.0-alpha.17",
+    "vitepress": "^2.0.0-alpha.18",
     "vitepress-plugin-group-icons": "^1.7.5",
-    "vitepress-plugin-llms": "^1.13.1",
-    "vitest": "^4.1.9"
+    "vitepress-plugin-llms": "^1.13.2",
+    "vitest": "^4.1.10"
   },
   "engines": {
     "node": ">=20"