mailchannels-sdk 1.1.0 → 1.3.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/.agents/skills/mailchannels-js/resources/suppressions.md

@@ -10,8 +10,8 @@ import { MailChannels } from 'mailchannels-sdk'
 
 const mc = new MailChannels('YOUR-API-KEY')
 
-const { success, error } = await mc.suppressions.create({
-  entries: [
+const { success, error } = await mc.suppressions.create(
+  [
     {
       recipient: 'out@example.net',
       types: ['non-transactional'],          // optional; defaults to non-transactional
@@ -22,8 +22,8 @@ const { success, error } = await mc.suppressions.create({
       types: ['transactional', 'non-transactional']
     }
   ],
-  addToSubAccounts: true   // parent only; copies entries to every sub-account
-})
+  { addToSubAccounts: true }   // parent only; copies entries to every sub-account
+)
 ```
 
 Constraints:
@@ -83,9 +83,9 @@ that recipient regardless of origin.
 
 ### Patterns
 
-- **Preference center opt-out**: set `type` according to the email category, e.g. `non-transactional` for marketing 
-  emails, `transactional` for order updates, and so on. 
+- **Preference center opt-out**: set `types` according to the email category, e.g. `non-transactional` for marketing
+  emails, `transactional` for order updates, and so on.
   Configure `addToSubAccounts` depending on whether the preference applies to all sub-accounts or just the parent account.
   Add a note to indicate the source, e.g. "Opted out via preference center".
-- **Migrating from another ESP**: bulk-create with `addToSubAccounts: true` so every tenant
+- **Migrating from another ESP**: bulk-create with option `addToSubAccounts: true` so every tenant
   inherits the list.

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.5.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,8 @@ const createMetricsBuckets = (count) => [{
 const createAccountState = (apiKey) => ({
 	apiKey,
 	customerHandle: createId("customer"),
+	limit: { sends: 1e5 },
+	customTrackingDomains: [],
 	dkimKeysByDomain: /* @__PURE__ */ new Map(),
 	messages: [],
 	subAccounts: /* @__PURE__ */ new Map(),
@@ -101,6 +103,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 +137,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 +211,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 +254,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 +336,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 +440,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 +464,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 +472,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$/);
@@ -519,16 +601,20 @@ const createEmailApiHandler = ({ logRequests = true } = {}) => {
 					return;
 				}
 				if (suffix === "usage" && method === "GET") {
+					const subLimitSends = subAccount.limit?.sends ?? -1;
+					const monthlyLimit = subLimitSends === -1 ? account.limit.sends : subLimitSends;
 					sendJson(response, 200, {
 						period_end_date: currentTimestamp(),
 						period_start_date: new Date((/* @__PURE__ */ new Date()).setDate(1)).toISOString(),
-						total_usage: subAccount.usage
+						total_usage: subAccount.usage,
+						monthly_limit: monthlyLimit
 					});
 					return;
 				}
 			}
 			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 +632,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 +651,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 +666,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),
@@ -633,10 +724,21 @@ const createEmailApiHandler = ({ logRequests = true } = {}) => {
 				return;
 			}
 			if (url.pathname === "/tx/v1/usage" && method === "GET") {
+				let totalUsage = account.messages.length;
+				let monthlyLimit = account.limit.sends;
+				if (scopeHandle) {
+					const subAccount = account.subAccounts.get(scopeHandle);
+					if (subAccount) {
+						totalUsage = subAccount.usage;
+						const subLimitSends = subAccount.limit?.sends ?? -1;
+						monthlyLimit = subLimitSends === -1 ? account.limit.sends : subLimitSends;
+					}
+				}
 				sendJson(response, 200, {
 					period_end_date: currentTimestamp(),
 					period_start_date: new Date((/* @__PURE__ */ new Date()).setDate(1)).toISOString(),
-					total_usage: account.messages.length
+					total_usage: totalUsage,
+					monthly_limit: monthlyLimit
 				});
 				return;
 			}
@@ -678,7 +780,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 {