mailchannels-sdk 0.7.4 → 0.7.5

package/dist/mailchannels.d.mts

@@ -637,6 +637,13 @@ type WebhooksListResponse = DataResponse<string[]>;
 //#endregion
 //#region src/types/webhooks/signing-key.d.ts
 type WebhooksSigningKeyResponse = DataResponse<{
+  /**
+   * The ID of the key.
+   */
+  id: string;
+  /**
+   * The public key used to verify webhook signatures.
+   */
   key: string;
 }>;
 //#endregion
@@ -674,6 +681,26 @@ type WebhooksValidateResponse = DataResponse<{
   }[];
 }>;
 //#endregion
+//#region src/types/webhooks/verify.d.ts
+interface WebhooksVerifyOptions {
+  /**
+   * The raw body of the incoming webhook request as a string. This should be the exact payload received from the webhook, without any modifications or parsing, to ensure accurate signature verification.
+   */
+  payload: string;
+  /**
+   * The headers of the incoming webhook request as a record of key-value pairs. These headers should include `content-digest`, `signature`, and `signature-input` required for validating the authenticity of the webhook request.
+   */
+  headers: Record<string, string> | {
+    "content-digest": string;
+    "signature": string;
+    "signature-input": string;
+  };
+  /**
+   * The public key used to verify the webhook signature. If not provided, the SDK will attempt to retrieve the appropriate public key based on the `keyId` specified in the `signature-input` header.
+   */
+  publicKey?: string;
+}
+//#endregion
 //#region src/modules/webhooks.d.ts
 declare class Webhooks {
   protected mailchannels: MailChannelsClient;
@@ -726,6 +753,25 @@ declare class Webhooks {
    * ```
    */
   validate(requestId?: string): Promise<WebhooksValidateResponse>;
+  /**
+   * Verifies the authenticity of incoming webhook requests by validating their signatures using the provided options.
+   * @param options - The options for verifying the webhook.
+   * @example
+   * ```ts
+   * const isValid = await Webhooks.verify({ payload: rawBody, headers })
+   * ```
+   */
+  static verify(options: WebhooksVerifyOptions): Promise<boolean>;
+  /**
+   * Verifies the authenticity of incoming webhook requests by validating their signatures using the provided options.
+   * @param options - The options for verifying the webhook.
+   * @example
+   * ```ts
+   * const mailchannels = new MailChannels('your-api-key')
+   * const isValid = await mailchannels.webhooks.verify({ payload: rawBody, headers })
+   * ```
+   */
+  verify(options: WebhooksVerifyOptions): Promise<boolean>;
 }
 //#endregion
 //#region src/types/sub-accounts/create.d.ts
@@ -859,6 +905,7 @@ declare class SubAccounts {
   /**
    * Deletes the sub-account identified by its handle.
    * @param handle - Handle of sub-account to be deleted.
+   * @example
    * ```ts
    * const mailchannels = new MailChannels('your-api-key')
    * const { success, error } = await mailchannels.subAccounts.delete('validhandle123')
@@ -1372,12 +1419,12 @@ declare class Suppressions {
   delete(recipient: string, source?: SuppressionsSource): Promise<SuccessResponse>;
   /**
    * Retrieve suppression entries associated with the specified account. Supports filtering by recipient, source and creation date range. The response is paginated, with a default limit of `1000` entries per page and an offset of `0`.
+   * @param options - Options to filter and customize the suppression entries retrieval.
    * @example
    * ```ts
    * const mailchannels = new MailChannels('your-api-key')
    * const { data, error } = await mailchannels.suppressions.list();
    * ```
-   * @param options - Options to filter and customize the suppression entries retrieval.
    */
   list(options?: SuppressionsListOptions): Promise<SuppressionsListResponse>;
 }
@@ -1914,15 +1961,15 @@ interface ServiceReportOptions {
    * The SMTP envelope information.
    */
   smtpEnvelopeInformation?: {
-    ehlo: string;
-    mailFrom: string;
-    rcptTo: string;
+    ehlo?: string;
+    mailFrom?: string;
+    rcptTo?: string;
   };
   /**
    * The sending host information.
    */
   sendingHostInformation?: {
-    name: string;
+    name?: string;
   };
 }
 //#endregion
@@ -1962,6 +2009,81 @@ declare class Service {
   report(options: ServiceReportOptions): Promise<SuccessResponse>;
 }
 //#endregion
+//#region src/types/webhooks/events.d.ts
+type WebhookEventType = "processed" | "delivered" | "open" | "click" | "hard-bounced" | "soft-bounced" | "dropped" | "complained" | "unsubscribed" | "test";
+interface WebhookEventBase<T extends WebhookEventType> {
+  /**
+   * The sender's email address
+   */
+  email?: string;
+  /**
+   * The MailChannels account ID that generated the webhook.
+   * If the message was sent by a sub-account, this field contains the sub-account handle.
+   */
+  customer_handle: string;
+  /**
+   * The Unix timestamp (in seconds) when the event occurred; the timezone is always UTC
+   */
+  timestamp: number;
+  /**
+   * The Message-Id of the message that generated the event
+   */
+  smtp_id?: string;
+  /**
+   * The type of event that occurred
+   */
+  event: T;
+  /**
+   * A unique identifier generated to track the original HTTP request
+   */
+  request_id?: string;
+  /**
+   * The campaign identifier for the message that generated the event
+   */
+  campaign_id?: string;
+  /**
+   * The recipients of the message
+   */
+  recipients?: string[];
+}
+interface WebhookEventProcessed extends WebhookEventBase<"processed"> {}
+interface WebhookEventDelivered extends WebhookEventBase<"delivered"> {}
+interface WebhookEventWithTracking {
+  /**
+   * The User-Agent header given when the recipient opened the message
+   */
+  user_agent?: string;
+  /**
+   * The IP address of the host that made the HTTP request
+   */
+  ip?: string;
+}
+interface WebhookEventOpen extends WebhookEventBase<"open">, WebhookEventWithTracking {}
+interface WebhookEventClick extends WebhookEventBase<"click">, WebhookEventWithTracking {
+  /**
+   * The URL that was clicked by the recipient
+   */
+  url?: string;
+}
+interface WebhookEventWithStatus {
+  /**
+   * The SMTP status code that caused the bounce
+   */
+  status?: string;
+  /**
+   * A human-readable explanation of why the message hard-bounced
+   */
+  reason?: string;
+}
+interface WebhookEventHardBounced extends WebhookEventBase<"hard-bounced">, WebhookEventWithStatus {}
+interface WebhookEventSoftBounced extends WebhookEventBase<"soft-bounced">, WebhookEventWithStatus {}
+interface WebhookEventDropped extends WebhookEventBase<"dropped">, WebhookEventWithStatus {}
+interface WebhookEventComplained extends WebhookEventBase<"complained"> {}
+interface WebhookEventUnsubscribed extends WebhookEventBase<"unsubscribed"> {}
+interface WebhookEventTest extends Omit<WebhookEventBase<"test">, "recipients" | "campaign_id"> {}
+type WebhookEvent = WebhookEventProcessed | WebhookEventDelivered | WebhookEventOpen | WebhookEventClick | WebhookEventHardBounced | WebhookEventSoftBounced | WebhookEventDropped | WebhookEventComplained | WebhookEventUnsubscribed | WebhookEventTest;
+type WebhookEvents = WebhookEvent[];
+//#endregion
 //#region src/mailchannels.d.ts
 declare class MailChannels extends MailChannelsClient {
   readonly emails: Emails;
@@ -1976,4 +2098,4 @@ declare class MailChannels extends MailChannelsClient {
   constructor(key: string);
 }
 //#endregion
-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, Webhooks, WebhooksListResponse, WebhooksSigningKeyResponse, WebhooksValidateResponse };
+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, WebhooksListResponse, WebhooksSigningKeyResponse, WebhooksValidateResponse, WebhooksVerifyOptions };

package/dist/mailchannels.mjs

@@ -1,4 +1,6 @@
 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";
 	#headers;
@@ -85,9 +87,15 @@ const validatePagination = (pagination = {}) => {
 	if (typeof offset === "number" && offset < 0) return createError("Offset must be greater than or equal to 0.");
 	return null;
 };
+/**
+* Validates if a string is a valid email address
+*/
 const isValidEmail = (email) => {
 	return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
 };
+/**
+* Parses name-address pair string to MailChannels format
+*/
 const parseRecipientString = (input) => {
 	const trimmed = input.trim();
 	const match = trimmed.match(/^([^<]*)<([^>]*)>$/);
@@ -102,6 +110,9 @@ const parseRecipientString = (input) => {
 	if (!isValidEmail(trimmed)) return void 0;
 	return { email: trimmed };
 };
+/**
+* Parses any recipient format to MailChannels format
+*/
 const parseRecipient = (recipient) => {
 	if (typeof recipient === "string") return parseRecipientString(recipient);
 	if (!recipient?.email || !isValidEmail(recipient.email)) return void 0;
@@ -110,12 +121,20 @@ const parseRecipient = (recipient) => {
 		name: recipient.name
 	};
 };
+/**
+* Parses any array of recipients format to MailChannels format
+*/
 const parseArrayRecipients = (recipients) => {
 	if (!recipients) return void 0;
 	const filtered = (typeof recipients === "string" ? [parseRecipientString(recipients)] : Array.isArray(recipients) ? recipients.map(parseRecipient) : [recipients]).filter((recipient) => Boolean(recipient));
 	return filtered.length > 0 ? filtered : void 0;
 };
 const stripPemHeaders = (pem) => pem.replace(/-----[^-]+-----|\s|#.*$/gm, "");
+/**
+* Recursively removes undefined values from objects and arrays.
+* @param data - The data to clean
+* @returns The cleaned data with `undefined` properties removed
+*/
 const clean = (data) => {
 	if (Array.isArray(data)) {
 		const result = [];
@@ -260,12 +279,62 @@ var Emails = class {
 			error: null
 		};
 	}
+	/**
+	* Sends an email message to one or more recipients.
+	* @param options - The email options to send.
+	* @param dryRun - When set to `true`, the message will not be sent. Instead, the fully rendered message will be returned in the `data` property of the response. The default value is `false`.
+	* @example
+	* ```ts
+	* const mailchannels = new MailChannels('your-api-key')
+	* const { success, data, error } = await mailchannels.emails.send({
+	*   to: 'to@example.com',
+	*   from: 'from@example.com',
+	*   subject: 'Test',
+	*   html: 'Test'
+	* })
+	* ```
+	*/
 	async send(options, dryRun = false) {
 		return this._sendEmail(options, { dryRun });
 	}
+	/**
+	* Queues an email message for asynchronous processing and returns immediately with a request ID.
+	*
+	* The email will be processed in the background, and you'll receive webhook events for all delivery status updates (e.g. `dropped`, `processed`, `delivered`, `hard-bounced`). These webhook events are identical to those sent for the synchronous /send endpoint.
+	*
+	* Use this endpoint when you need to send emails without waiting for processing to complete. This can improve your application's response time, especially when sending to multiple recipients.
+	* @param options - The email options to send.
+	* @example
+	* ```ts
+	* const mailchannels = new MailChannels('your-api-key')
+	* const { data, error } = await mailchannels.emails.sendAsync({
+	*   to: 'to@example.com',
+	*   from: 'from@example.com',
+	*   subject: 'Test',
+	*   html: 'Test'
+	* })
+	* ```
+	*/
 	async sendAsync(options) {
 		return this._sendEmail(options, { async: true });
 	}
+	/**
+	* 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.
+	* @param options - The domain options to check.
+	* @example
+	* ```ts
+	* const mailchannels = new MailChannels('your-api-key')
+	* const { data, error } = await mailchannels.emails.checkDomain({
+	*   dkim: [{
+	*     domain: 'example.com',
+	*     privateKey: 'your-private-key',
+	*     selector: 'mailchannels'
+	*   }],
+	*   domain: 'example.com',
+	*   senderId: 'sender-id'
+	* })
+	* ```
+	*/
 	async checkDomain(options) {
 		let error = null;
 		const { dkim, domain, senderId } = options;
@@ -311,6 +380,18 @@ var Emails = class {
 			error: null
 		};
 	}
+	/**
+	* Create a DKIM key pair for a specified domain and selector using the specified algorithm and key length, for the current customer.
+	* @param domain - The domain to create the DKIM key for.
+	* @param options - DKIM key creation options.
+	* @example
+	* ```ts
+	* const mailchannels = new MailChannels('your-api-key')
+	* const { data, error } = await mailchannels.emails.createDkimKey('example.com', {
+	*   selector: 'mailchannels'
+	* })
+	* ```
+	*/
 	async createDkimKey(domain, options) {
 		let error = null;
 		if (!options.selector || options.selector.length > 63) {
@@ -358,6 +439,18 @@ var Emails = class {
 			error: null
 		};
 	}
+	/**
+	* Search for DKIM keys by domain, with optional filters. If selector is provided, at most one key will be returned.
+	* @param domain - The domain to search DKIM keys for.
+	* @param options - The options to filter DKIM keys by.
+	* @example
+	* ```ts
+	* const mailchannels = new MailChannels('your-api-key')
+	* const { data, error } = await mailchannels.getDkimKeys('example.com', {
+	*   includeDnsRecord: true
+	* })
+	* ```
+	*/
 	async getDkimKeys(domain, options) {
 		let error = null;
 		if (options?.selector && options.selector.length > 63) {
@@ -412,6 +505,18 @@ var Emails = class {
 			error: null
 		};
 	}
+	/**
+	* Update fields of an existing DKIM key pair for the specified domain and selector, for the current customer. Currently, only the `status` field can be updated.
+	* @param domain - The domain the DKIM key belongs to.
+	* @param options - The options to update the DKIM key.
+	* @example
+	* ```ts
+	* const mailchannels = new MailChannels('your-api-key')
+	* const { success, error } = await mailchannels.emails.updateDkimKey('example.com', {
+	*   selector: 'mailchannels',
+	*   status: 'retired'
+	* })
+	*/
 	async updateDkimKey(domain, options) {
 		let error = null;
 		if (!options.selector || options.selector.length > 63) {
@@ -438,6 +543,22 @@ var Emails = class {
 			error
 		};
 	}
+	/**
+	* Rotate an active DKIM key pair. Mark the original key as `rotated`, and create a new key pair with the required new key selector, reusing the same algorithm and key length. The rotated key remains valid for signing for a 3-day grace period, and is automatically changed to `retired` 2 weeks after rotation. Publish the new key to its DNS TXT record before rotated key expires for signing as emails sent with an unpublished key will fail DKIM validation by receiving providers. After the grace period, only the new key is valid for signing if published.
+	* @param domain - The domain the DKIM key belongs to.
+	* @param selector - The selector of the DKIM key to rotate.
+	* @param options - The options to rotate the DKIM key.
+	* @param options.newKey.selector - The selector for the new key pair. Must be a maximum of 63 characters.
+	* @example
+	* ```ts
+	* const mailchannels = new MailChannels('your-api-key')
+	* const { data, error } = await mailchannels.emails.rotateDkimKey('example.com', 'mailchannels', {
+	*   newKey: {
+	*     selector: 'new-selector'
+	*   }
+	* })
+	* ```
+	*/
 	async rotateDkimKey(domain, selector, options) {
 		let error = null;
 		if (!selector || selector.length > 63) {
@@ -505,10 +626,86 @@ var Emails = class {
 		};
 	}
 };
-var Webhooks = class {
+const HMAC_SHA256 = {
+	name: "HMAC",
+	hash: "SHA-256"
+};
+const ED25519 = {
+	name: "Ed25519",
+	namedCurve: "Ed25519"
+};
+const encoder = new TextEncoder();
+const DEFAULT_TOLERANCE = 300;
+const HEADER_CONTENT_DIGEST = "content-digest";
+const HEADER_SIGNATURE = "signature";
+const HEADER_SIGNATURE_INPUT = "signature-input";
+const validateContentDigest = async (header, body) => {
+	const match = header.match(/^(.*?)=:(.*?):$/);
+	if (!match) return false;
+	const [, algorithm, hash] = match;
+	if (!algorithm || !hash) return false;
+	const normalizedAlgorithm = algorithm.replace("-", "").toLowerCase();
+	if (!["sha256"].includes(normalizedAlgorithm)) return false;
+	const signatureBuffer = await subtle.digest(HMAC_SHA256.hash, encoder.encode(body));
+	return Buffer.from(signatureBuffer).toString("base64") === hash;
+};
+const extractSignature = (signatureHeader) => {
+	const signatureMatch = signatureHeader.match(/sig_\d+=:([^:]+):/);
+	return signatureMatch && signatureMatch[1] ? signatureMatch[1] : null;
+};
+const extractInputValues = (header) => {
+	const match = header.match(/^(\w+)=\(([^)]+)\);created=(\d+);alg="([^"]+)";keyid="([^"]+)"$/);
+	if (!match) return null;
+	return {
+		name: match[1],
+		timestamp: Number.parseInt(match[3], 10),
+		algorithm: match[4],
+		keyId: match[5]
+	};
+};
+async function isValidWebhook(options) {
+	const { payload, headers } = options;
+	const contentDigest = headers[HEADER_CONTENT_DIGEST];
+	const messageSignature = headers[HEADER_SIGNATURE];
+	const signatureInput = headers[HEADER_SIGNATURE_INPUT];
+	if (!payload || !contentDigest || !messageSignature || !signatureInput || !await validateContentDigest(contentDigest, payload)) return false;
+	const signature = extractSignature(messageSignature);
+	if (!signature) return false;
+	const values = extractInputValues(signatureInput);
+	if (!values) return false;
+	if (Math.floor(Date.now() / 1e3) - values.timestamp > DEFAULT_TOLERANCE) return false;
+	const signingString = `"content-digest": ${contentDigest}
+"@signature-params": ("content-digest");created=${values.timestamp};alg="${values.algorithm}";keyid="${values.keyId}"`;
+	let publicKey = options.publicKey;
+	if (!publicKey) {
+		const publicKeyResponse = await $fetch("/tx/v1/webhook/public-key", {
+			baseURL: "https://api.mailchannels.net",
+			query: { id: values.keyId }
+		}).catch(() => null);
+		if (!publicKeyResponse) return false;
+		publicKey = publicKeyResponse.key;
+	}
+	publicKey = stripPemHeaders(publicKey);
+	const encoding = "base64";
+	const format = "spki";
+	const publicKeyBuffer = Buffer.from(publicKey, encoding);
+	const webhookSignatureBuffer = Buffer.from(signature, encoding);
+	const key = await subtle.importKey(format, publicKeyBuffer, ED25519, false, ["verify"]);
+	return subtle.verify(ED25519.name, key, webhookSignatureBuffer, encoder.encode(signingString));
+}
+var Webhooks = class Webhooks {
 	constructor(mailchannels) {
 		this.mailchannels = mailchannels;
 	}
+	/**
+	* Enrolls the customer to receive event notifications via webhooks.
+	* @param endpoint - The URL to receive event notifications. Must be no longer than `8000` characters.
+	* @example
+	* ```ts
+	* const mailchannels = new MailChannels('your-api-key')
+	* const { success, error } = mailchannels.webhooks.enroll('https://example.com/api/webhooks/mailchannels')
+	* ```
+	*/
 	async enroll(endpoint) {
 		let error = null;
 		if (!endpoint) {
@@ -538,6 +735,14 @@ var Webhooks = class {
 			error
 		};
 	}
+	/**
+	* Retrieves all registered webhook endpoints associated with the customer.
+	* @example
+	* ```ts
+	* const mailchannels = new MailChannels('your-api-key')
+	* const { data, error } = await mailchannels.webhooks.list()
+	* ```
+	*/
 	async list() {
 		let error = null;
 		const response = await this.mailchannels.get("/tx/v1/webhook", { onResponseError: async ({ response }) => {
@@ -555,6 +760,14 @@ var Webhooks = class {
 			error: null
 		};
 	}
+	/**
+	* Deletes all registered webhook endpoints for the customer.
+	* @example
+	* ```ts
+	* const mailchannels = new MailChannels('your-api-key')
+	* const { success, error } = await mailchannels.webhooks.delete()
+	* ```
+	*/
 	async delete() {
 		let error = null;
 		await this.mailchannels.delete("/tx/v1/webhook", { onResponseError: async ({ response }) => {
@@ -567,6 +780,15 @@ var Webhooks = class {
 			error
 		};
 	}
+	/**
+	* Retrieves the public key used to verify signatures on incoming webhook payloads.
+	* @param id - The ID of the key.
+	* @example
+	* ```ts
+	* const mailchannels = new MailChannels('your-api-key')
+	* const { data, error } = await mailchannels.webhooks.getSigningKey('key-id')
+	* ```
+	*/
 	async getSigningKey(id) {
 		let error = null;
 		const response = await this.mailchannels.get("/tx/v1/webhook/public-key", {
@@ -586,10 +808,22 @@ var Webhooks = class {
 			error
 		};
 		return {
-			data: clean({ key: response.key }),
+			data: clean({
+				id: response.id,
+				key: response.key
+			}),
 			error: null
 		};
 	}
+	/**
+	* Validates whether your enrolled webhook(s) respond with an HTTP `2xx` status code. Sends a test request to each webhook containing your customer handle, a hardcoded event type (`test`), a hardcoded sender email (`test@mailchannels.com`), a timestamp, a request ID (provided or generated), and an SMTP ID. The response includes the HTTP status code and body returned by each webhook.
+	* @param requestId - Optional identifier in the webhook payload. If not provided, a value will be automatically generated. Must not exceed 28 characters.
+	* @example
+	* ```ts
+	* const mailchannels = new MailChannels('your-api-key')
+	* const { data, error } = await mailchannels.webhooks.validate('optional-request-id')
+	* ```
+	*/
 	async validate(requestId) {
 		let error = null;
 		if (requestId && requestId.length > 28) {
@@ -623,6 +857,29 @@ var Webhooks = class {
 			error: null
 		};
 	}
+	/**
+	* Verifies the authenticity of incoming webhook requests by validating their signatures using the provided options.
+	* @param options - The options for verifying the webhook.
+	* @example
+	* ```ts
+	* const isValid = await Webhooks.verify({ payload: rawBody, headers })
+	* ```
+	*/
+	static async verify(options) {
+		return isValidWebhook(options).catch(() => false);
+	}
+	/**
+	* Verifies the authenticity of incoming webhook requests by validating their signatures using the provided options.
+	* @param options - The options for verifying the webhook.
+	* @example
+	* ```ts
+	* const mailchannels = new MailChannels('your-api-key')
+	* const isValid = await mailchannels.webhooks.verify({ payload: rawBody, headers })
+	* ```
+	*/
+	async verify(options) {
+		return Webhooks.verify(options);
+	}
 };
 var SubAccounts = class SubAccounts {
 	static COMPANY_PATTERN = /^.{3,128}$/;
@@ -630,6 +887,16 @@ var SubAccounts = class SubAccounts {
 	constructor(mailchannels) {
 		this.mailchannels = mailchannels;
 	}
+	/**
+	* Creates a new sub-account under the parent account. Each sub-account must have a unique handle composed solely of lowercase alphanumeric characters. If no handle is provided, a random handle will be generated. Note that Sub-accounts are only available to parent accounts on 100K and higher plans.
+	* @param companyName - The name of the company associated with the sub-account. This name is used for display purposes only and does not affect the functionality of the sub-account. The length must be between 3 and 128 characters.
+	* @param handle - A unique name for the sub-account to be created. The length must be between 3 and 128 characters, and it may contain only lowercase letters and numbers. If not provided, a random handle will be generated.
+	* @example
+	* ```ts
+	* const mailchannels = new MailChannels('your-api-key')
+	* const { data, error } = await mailchannels.subAccounts.create('My Company', 'validhandle123')
+	* ```
+	*/
 	async create(companyName, handle) {
 		let error = null;
 		if (!SubAccounts.COMPANY_PATTERN.test(companyName)) {
@@ -676,6 +943,15 @@ var SubAccounts = class SubAccounts {
 			error: null
 		};
 	}
+	/**
+	* Retrieves all sub-accounts associated with the parent account. The response is paginated with a default limit of 1000 sub-accounts per page and an offset of 0.
+	* @param options - The options to filter the list of sub-accounts.
+	* @example
+	* ```ts
+	* const mailchannels = new MailChannels('your-api-key')
+	* const { data, error } = await mailchannels.subAccounts.list()
+	* ```
+	*/
 	async list(options) {
 		let error = null;
 		error = validatePagination({
@@ -708,6 +984,15 @@ var SubAccounts = class SubAccounts {
 			error: null
 		};
 	}
+	/**
+	* Deletes the sub-account identified by its handle.
+	* @param handle - Handle of sub-account to be deleted.
+	* @example
+	* ```ts
+	* const mailchannels = new MailChannels('your-api-key')
+	* const { success, error } = await mailchannels.subAccounts.delete('validhandle123')
+	* ```
+	*/
 	async delete(handle) {
 		let error = null;
 		if (!handle) {
@@ -727,6 +1012,15 @@ var SubAccounts = class SubAccounts {
 			error
 		};
 	}
+	/**
+	* Suspends the sub-account identified by its handle. This action disables the account, preventing it from sending any emails until it is reactivated.
+	* @param handle - Handle of sub-account to be suspended.
+	* @example
+	* ```ts
+	* const mailchannels = new MailChannels('your-api-key')
+	* const { success, error } = await mailchannels.subAccounts.suspend('validhandle123')
+	* ```
+	*/
 	async suspend(handle) {
 		let error = null;
 		if (!handle) {
@@ -746,6 +1040,15 @@ var SubAccounts = class SubAccounts {
 			error
 		};
 	}
+	/**
+	* Activates a suspended sub-account identified by its handle, restoring its ability to send emails.
+	* @param handle - Handle of sub-account to be activated.
+	* @example
+	* ```ts
+	* const mailchannels = new MailChannels('your-api-key')
+	* const { success, error } = await mailchannels.subAccounts.activate('validhandle123')
+	* ```
+	*/
 	async activate(handle) {
 		let error = null;
 		if (!handle) {
@@ -768,6 +1071,15 @@ var SubAccounts = class SubAccounts {
 			error
 		};
 	}
+	/**
+	* Creates a new API key for the specified sub-account.
+	* @param handle - Handle of the sub-account to create API key for.
+	* @example
+	* ```ts
+	* const mailchannels = new MailChannels('your-api-key')
+	* const { data, error } = await mailchannels.subAccounts.createApiKey('validhandle123')
+	* ```
+	*/
 	async createApiKey(handle) {
 		let error = null;
 		if (!handle) {
@@ -799,6 +1111,16 @@ var SubAccounts = class SubAccounts {
 			error: null
 		};
 	}
+	/**
+	* Retrieves details of all API keys associated with the specified sub-account. For security reasons, the full API key is not returned; only the key ID and a partially redacted version are provided.
+	* @param handle - Handle of the sub-account to retrieve the API key for.
+	* @param options - The options to filter the list of API keys.
+	* @example
+	* ```ts
+	* const mailchannels = new MailChannels('your-api-key')
+	* const { data, error } = await mailchannels.subAccounts.listApiKeys('validhandle123')
+	* ```
+	*/
 	async listApiKeys(handle, options) {
 		let error = null;
 		if (!handle) {
@@ -834,6 +1156,16 @@ var SubAccounts = class SubAccounts {
 			error: null
 		};
 	}
+	/**
+	* Deletes the API key identified by its ID for the specified sub-account.
+	* @param handle - Handle of the sub-account for which the API key should be deleted.
+	* @param id - The ID of the API key to delete.
+	* @example
+	* ```ts
+	* const mailchannels = new MailChannels('your-api-key')
+	* const { success, error } = await mailchannels.subAccounts.deleteApiKey('validhandle123', 1)
+	* ```
+	*/
 	async deleteApiKey(handle, id) {
 		let error = null;
 		if (!handle) {
@@ -853,6 +1185,15 @@ var SubAccounts = class SubAccounts {
 			error
 		};
 	}
+	/**
+	* Creates a new SMTP password for the specified sub-account.
+	* @param handle - Handle of the sub-account to create SMTP password for.
+	* @example
+	* ```ts
+	* const mailchannels = new MailChannels('your-api-key')
+	* const { data, error } = await mailchannels.subAccounts.createSmtpPassword('validhandle123')
+	* ```
+	*/
 	async createSmtpPassword(handle) {
 		let error = null;
 		if (!handle) {
@@ -885,6 +1226,15 @@ var SubAccounts = class SubAccounts {
 			error: null
 		};
 	}
+	/**
+	* Retrieves details of all SMTP passwords associated with the specified sub-account. For security, the full SMTP password is not returned; only the password ID and a partially redacted version are provided.
+	* @param handle - Handle of the sub-account to retrieve the SMTP password for.
+	* @example
+	* ```ts
+	* const mailchannels = new MailChannels('your-api-key')
+	* const { data, error } = await mailchannels.subAccounts.listSmtpPasswords('validhandle123')
+	* ```
+	*/
 	async listSmtpPasswords(handle) {
 		let error = null;
 		if (!handle) {
@@ -913,6 +1263,16 @@ var SubAccounts = class SubAccounts {
 			error: null
 		};
 	}
+	/**
+	* Deletes the SMTP password identified by its ID for the specified sub-account.
+	* @param handle - Handle of the sub-account for which the SMTP password should be deleted.
+	* @param id - The ID of the SMTP password to delete.
+	* @example
+	* ```ts
+	* const mailchannels = new MailChannels('your-api-key')
+	* const { success, error } = await mailchannels.subAccounts.deleteSmtpPassword('validhandle123', 1)
+	* ```
+	*/
 	async deleteSmtpPassword(handle, id) {
 		let error = null;
 		if (!handle) {
@@ -932,6 +1292,15 @@ var SubAccounts = class SubAccounts {
 			error
 		};
 	}
+	/**
+	* Retrieves the limit of a specified sub-account. A value of `-1` indicates that the sub-account inherits the parent account's limit, allowing the sub-account to utilize any remaining capacity within the parent account's allocation.
+	* @param handle - Handle of the sub-account to retrieve the limit for.
+	* @example
+	* ```ts
+	* const mailchannels = new MailChannels('your-api-key')
+	* const { data, error } = await mailchannels.subAccounts.getLimit('validhandle123')
+	* ```
+	*/
 	async getLimit(handle) {
 		let error = null;
 		if (!handle) {
@@ -956,6 +1325,16 @@ var SubAccounts = class SubAccounts {
 			error: null
 		};
 	}
+	/**
+	* Sets the limit for the specified sub-account.
+	* @param handle - Handle of the sub-account to set limit for.
+	* @param limit - The limits to set for the sub-account. The minimum allowed sends is `0`
+	* @example
+	* ```ts
+	* const mailchannels = new MailChannels('your-api-key')
+	* const { success, error } = await mailchannels.subAccounts.setLimit('validhandle123', { sends: 1000 })
+	* ```
+	*/
 	async setLimit(handle, limit) {
 		let error = null;
 		if (!handle) {
@@ -981,6 +1360,15 @@ var SubAccounts = class SubAccounts {
 			error
 		};
 	}
+	/**
+	* Deletes the limit for the specified sub-account. After a successful deletion, the specified sub-account will be limited to the parent account's limit.
+	* @param handle - Handle of the sub-account to delete limit for.
+	* @example
+	* ```ts
+	* const mailchannels = new MailChannels('your-api-key')
+	* const { success, error } = await mailchannels.subAccounts.deleteLimit('validhandle123')
+	* ```
+	*/
 	async deleteLimit(handle) {
 		let error = null;
 		if (!handle) {
@@ -1000,6 +1388,15 @@ var SubAccounts = class SubAccounts {
 			error
 		};
 	}
+	/**
+	* Retrieves usage statistics for the specified sub-account during the current billing period.
+	* @param handle - Handle of the sub-account to query usage stats for.
+	* @example
+	* ```ts
+	* const mailchannels = new MailChannels('your-api-key')
+	* const { data, error } = await mailchannels.subAccounts.getUsage('validhandle123')
+	* ```
+	*/
 	async getUsage(handle) {
 		let error = null;
 		if (!handle) {
@@ -1033,6 +1430,15 @@ var Metrics = class {
 	constructor(mailchannels) {
 		this.mailchannels = mailchannels;
 	}
+	/**
+	* Retrieve engagement metrics for messages sent from your account, including counts of open and click events. Supports optional filters for time range, and campaign ID.
+	* @param options - Options to filter and customize the engagement metrics retrieval.
+	* @example
+	* ```ts
+	* const mailchannels = new MailChannels('your-api-key')
+	* const { data, error } = await mailchannels.metrics.engagement()
+	* ```
+	*/
 	async engagement(options) {
 		let error = null;
 		const response = await this.mailchannels.get("/tx/v1/metrics/engagement", {
@@ -1071,6 +1477,15 @@ var Metrics = class {
 			error: null
 		};
 	}
+	/**
+	* 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.
+	* @param options - Options to filter and customize the performance metrics retrieval.
+	* @example
+	* ```ts
+	* const mailchannels = new MailChannels('your-api-key')
+	* const { data, error } = await mailchannels.metrics.performance()
+	* ```
+	*/
 	async performance(options) {
 		let error = null;
 		const response = await this.mailchannels.get("/tx/v1/metrics/performance", {
@@ -1107,6 +1522,15 @@ var Metrics = class {
 			error: null
 		};
 	}
+	/**
+	* Retrieve recipient behaviour metrics for messages sent from your account, including counts of unsubscribed events. Supports optional filters for time range, and campaign ID.
+	* @param options - Options to filter and customize the recipient behaviour metrics retrieval.
+	* @example
+	* ```ts
+	* const mailchannels = new MailChannels('your-api-key')
+	* const { data, error } = await mailchannels.metrics.recipientBehaviour()
+	* ```
+	*/
 	async recipientBehaviour(options) {
 		let error = null;
 		const response = await this.mailchannels.get("/tx/v1/metrics/recipient-behaviour", {
@@ -1141,6 +1565,15 @@ var Metrics = class {
 			error: null
 		};
 	}
+	/**
+	* Retrieve volume metrics for messages sent from your account, including counts of processed, delivered and dropped events. Supports optional filters for time range and campaign ID.
+	* @param options - Options to filter and customize the volume metrics retrieval.
+	* @example
+	* ```ts
+	* const mailchannels = new MailChannels('your-api-key')
+	* const { data, error } = await mailchannels.metrics.volume()
+	* ```
+	*/
 	async volume(options) {
 		let error = null;
 		const response = await this.mailchannels.get("/tx/v1/metrics/volume", {
@@ -1177,6 +1610,14 @@ var Metrics = class {
 			error: null
 		};
 	}
+	/**
+	* Retrieves usage statistics during the current billing period.
+	* @example
+	* ```ts
+	* const mailchannels = new MailChannels('your-api-key')
+	* const { data, error } = await mailchannels.metrics.usage()
+	* ```
+	*/
 	async usage() {
 		let error = null;
 		const response = await this.mailchannels.get("/tx/v1/usage", { onResponseError: async ({ response }) => {
@@ -1198,6 +1639,16 @@ var Metrics = class {
 			error: null
 		};
 	}
+	/**
+	* Retrieves a list of senders, either sub-accounts or campaigns, with their associated message metrics. Sorted by total # of sent messages (processed + dropped). Supports optional filter for time range, and optional settings for limit, offset, and sort order. Note: senders without any messages in the given time range will not be included in the results. The default time range is from one month ago to now, and the default sort order is descending.
+	* @param type - The type of senders to retrieve metrics for. Can be either `sub-accounts` or `campaigns`.
+	* @param options - Optional filter options for time range, limit, offset, and sort order.
+	* @example
+	* ```ts
+	* const mailchannels = new MailChannels('your-api-key')
+	* const { data, error } = await mailchannels.metrics.senders('campaigns')
+	* ```
+	*/
 	async senders(type, options) {
 		let error = null;
 		error = validatePagination({
@@ -1244,6 +1695,16 @@ var Suppressions = class {
 	constructor(mailchannels) {
 		this.mailchannels = mailchannels;
 	}
+	/**
+	* Creates suppression entries for the specified account. Parent accounts can create suppression entries for all associated sub-accounts. If `types` is not provided, it defaults to `non-transactional`. The operation is atomic, meaning all entries are successfully added or none are added if an error occurs.
+	* @param options - The details of the suppression entries to create.
+	* @example
+	* ```ts
+	* const mailchannels = new MailChannels('your-api-key')
+	* const { success, error } = await mailchannels.suppressions.create({
+	* // ...
+	* });
+	*/
 	async create(options) {
 		let error = null;
 		const { addToSubAccounts, entries } = options;
@@ -1272,6 +1733,16 @@ var Suppressions = class {
 			error
 		};
 	}
+	/**
+	* Deletes suppression entry associated with the account based on the specified recipient and source.
+	* @param recipient - The email address of the suppression entry to delete.
+	* @param source - The source of the suppression entry to be deleted. If source is not provided, it defaults to `api`. If source is set to `all`, all suppression entries related to the specified recipient will be deleted.
+	* @example
+	* ```ts
+	* const mailchannels = new MailChannels('your-api-key')
+	* const { success, error } = await mailchannels.suppressions.delete('name@example.com', 'api');
+	* ```
+	*/
 	async delete(recipient, source) {
 		let error = null;
 		await this.mailchannels.delete(`/tx/v1/suppression-list/recipients/${recipient}`, {
@@ -1287,6 +1758,15 @@ var Suppressions = class {
 			error
 		};
 	}
+	/**
+	* Retrieve suppression entries associated with the specified account. Supports filtering by recipient, source and creation date range. The response is paginated, with a default limit of `1000` entries per page and an offset of `0`.
+	* @param options - Options to filter and customize the suppression entries retrieval.
+	* @example
+	* ```ts
+	* const mailchannels = new MailChannels('your-api-key')
+	* const { data, error } = await mailchannels.suppressions.list();
+	* ```
+	*/
 	async list(options) {
 		let error = null;
 		error = validatePagination({
@@ -1335,6 +1815,18 @@ var Domains = class {
 	constructor(mailchannels) {
 		this.mailchannels = mailchannels;
 	}
+	/**
+	* Provision a single domain to use MailChannels Inbound.
+	* @param options - The provision options and domain data.
+	* @example
+	* ```ts
+	* const mailchannels = new MailChannels('your-api-key')
+	* const { data, error } = await mailchannels.domains.provision({
+	*   domain: 'example.com',
+	*   subscriptionHandle: 'your-subscription-handle'
+	* })
+	* ```
+	*/
 	async provision(options) {
 		let error = null;
 		const { associateKey, overwrite, ...payload } = options;
@@ -1364,6 +1856,26 @@ var Domains = class {
 			error: null
 		};
 	}
+	/**
+	* Provision up to 1000 domains to use MailChannels Inbound.
+	* @param options - The options to provision the domains.
+	* @param domains - A list of domain data to provision.
+	* @example
+	* ```ts
+	* const mailchannels = new MailChannels('your-api-key')
+	* const { data, error } = await mailchannels.domains.bulkProvision({
+	*   subscriptionHandle: 'your-subscription-handle'
+	* }, [
+	*   {
+	*     domain: 'example.com',
+	*     admins: ['support@example.com']
+	*   },
+	*   {
+	*     domain: 'example2.com'
+	*   }
+	* ])
+	* ```
+	*/
 	async bulkProvision(options, domains) {
 		let error = null;
 		const { associateKey, overwrite, subscriptionHandle } = options;
@@ -1407,6 +1919,15 @@ var Domains = class {
 			error: null
 		};
 	}
+	/**
+	* Fetch a list of all domains associated with this API key.
+	* @param options - The options to filter the list of domains.
+	* @example
+	* ```ts
+	* const mailchannels = new MailChannels('your-api-key')
+	* const { data, error } = await mailchannels.domains.list()
+	* ```
+	*/
 	async list(options) {
 		let error = null;
 		error = validatePagination({
@@ -1438,6 +1959,15 @@ var Domains = class {
 			error: null
 		};
 	}
+	/**
+	* De-provision a domain to cease protecting it with MailChannels Inbound.
+	* @param domain - The domain name to be removed.
+	* @example
+	* ```ts
+	* const mailchannels = new MailChannels('your-api-key')
+	* const { success, error } = await mailchannels.domains.delete('example.com')
+	* ```
+	*/
 	async delete(domain) {
 		let error = null;
 		if (!domain) {
@@ -1460,6 +1990,19 @@ var Domains = class {
 			error
 		};
 	}
+	/**
+	* Add an entry to a domain blocklist or safelist.
+	* @param domain - The domain name.
+	* @param options - The options to add a list entry.
+	* @example
+	* ```ts
+	* const mailchannels = new MailChannels('your-api-key')
+	* const { data, error } = await mailchannels.domains.addListEntry('example.com', {
+	*   listName: 'safelist',
+	*   item: 'name@domain.com'
+	* })
+	* ```
+	*/
 	async addListEntry(domain, options) {
 		const { listName, item } = options;
 		let error = null;
@@ -1502,6 +2045,16 @@ var Domains = class {
 			error: null
 		};
 	}
+	/**
+	* Get domain list entries.
+	* @param domain - The domain name.
+	* @param listName - The name of the list to fetch. This can be a `blocklist`, `safelist`, `blacklist`, or `whitelist`.
+	* @example
+	* ```ts
+	* const mailchannels = new MailChannels('your-api-key')
+	* const { data, error } = await mailchannels.domains.listEntries('example.com', 'safelist')
+	* ```
+	*/
 	async listEntries(domain, listName) {
 		let error = null;
 		if (!domain) {
@@ -1540,6 +2093,19 @@ var Domains = class {
 			error: null
 		};
 	}
+	/**
+	* Delete item from domain list.
+	* @param email - The domain name whose list will be modified.
+	* @param options - The options for the list entry to delete.
+	* @example
+	* ```ts
+	* const mailchannels = new MailChannels('your-api-key')
+	* const { success, error } = await mailchannels.domains.deleteListEntry('example.com', {
+	*   listName: 'safelist',
+	*   item: 'name@domain.com'
+	* })
+	* ```
+	*/
 	async deleteListEntry(domain, options) {
 		const { listName, item } = options;
 		let error = null;
@@ -1573,6 +2139,15 @@ var Domains = class {
 			error
 		};
 	}
+	/**
+	* Generate a link that allows a user to log in as a domain administrator.
+	* @param domain - The domain name.
+	* @example
+	* ```ts
+	* const mailchannels = new MailChannels('your-api-key')
+	* const { data, error } = await mailchannels.domains.createLoginLink('example.com')
+	* ```
+	*/
 	async createLoginLink(domain) {
 		let error = null;
 		if (!domain) {
@@ -1601,6 +2176,23 @@ var Domains = class {
 			error: null
 		};
 	}
+	/**
+	* Sets the list of downstream addresses for the domain. This action deletes any existing downstream address for the domain before creating new ones. If the `records` parameter is an empty array, all downstream address records will be deleted.
+	* @param domain - The domain name.
+	* @param records - The list of records to set for the domain. A maximum of 10 records can be set.
+	* @example
+	* ```ts
+	* const mailchannels = new MailChannels('your-api-key')
+	* const { success, error } = await mailchannels.domains.setDownstreamAddress('example.com', [
+	*   {
+	*     port: 25,
+	*     priority: 10,
+	*     target: 'example.com.',
+	*     weight: 10
+	*   }
+	* ])
+	* ```
+	*/
 	async setDownstreamAddress(domain, records) {
 		let error = null;
 		if (!domain) {
@@ -1640,6 +2232,16 @@ var Domains = class {
 			error
 		};
 	}
+	/**
+	* Retrieve stored downstream addresses for the domain.
+	* @param domain - The domain name.
+	* @param options - The options to filter the list of downstream addresses.
+	* @example
+	* ```ts
+	* const mailchannels = new MailChannels('your-api-key')
+	* const { data, error } = await mailchannels.domains.listDownstreamAddresses('example.com')
+	* ```
+	*/
 	async listDownstreamAddresses(domain, options) {
 		let error = null;
 		if (!domain) {
@@ -1675,6 +2277,16 @@ var Domains = class {
 			error: null
 		};
 	}
+	/**
+	* Update the API key that is associated with a domain.
+	* @param domain - The domain name.
+	* @param key - The new API key to associate with this domain.
+	* @example
+	* ```ts
+	* const mailchannels = new MailChannels('your-api-key')
+	* const { success, error } = await mailchannels.domains.updateApiKey('example.com', 'your-api-key')
+	* ```
+	*/
 	async updateApiKey(domain, key) {
 		let error = null;
 		if (!domain) {
@@ -1707,6 +2319,15 @@ var Domains = class {
 			error
 		};
 	}
+	/**
+	* Generate a batch of links that allow a user to log in as a domain administrator to their different domains.
+	* @param domains - The list of domain names. Maximum of `1000` links per request.
+	* @example
+	* ```ts
+	* const mailchannels = new MailChannels('your-api-key')
+	* const { data, error } = await mailchannels.domains.bulkCreateLoginLinks(['example.com', 'example2.com'])
+	* ```
+	*/
 	async bulkCreateLoginLinks(domains) {
 		let error = null;
 		if (!domains || !domains.length) {
@@ -1746,6 +2367,18 @@ var Lists = class {
 	constructor(mailchannels) {
 		this.mailchannels = mailchannels;
 	}
+	/**
+	* Add item to account-level list
+	* @param options - The options for the list entry to add.
+	* @example
+	* ```ts
+	* const mailchannels = new MailChannels('your-api-key')
+	* const { data, error } = await mailchannels.lists.addListEntry({
+	*   listName: 'safelist',
+	*   item: 'name@domain.com'
+	* })
+	* ```
+	*/
 	async addListEntry(options) {
 		let error = null;
 		const { listName, item } = options;
@@ -1778,6 +2411,15 @@ var Lists = class {
 			error: null
 		};
 	}
+	/**
+	* Get account-level list entries.
+	* @param listName - The name of the list to fetch. This can be a `blocklist`, `safelist`, `blacklist`, or `whitelist`.
+	* @example
+	* ```ts
+	* const mailchannels = new MailChannels('your-api-key')
+	* const { data, error } = await mailchannels.lists.listEntries('safelist')
+	* ```
+	*/
 	async listEntries(listName) {
 		let error = null;
 		if (!listName) {
@@ -1806,6 +2448,18 @@ var Lists = class {
 			error: null
 		};
 	}
+	/**
+	* Delete item from account-level list.
+	* @param options - The options for the list entry to delete.
+	* @example
+	* ```ts
+	* const mailchannels = new MailChannels('your-api-key')
+	* const { success, error } = await mailchannels.lists.deleteListEntry({
+	*   listName: 'safelist',
+	*   item: 'name@domain.com'
+	* })
+	* ```
+	*/
 	async deleteListEntry(options) {
 		const { listName, item } = options;
 		let error = null;
@@ -1834,6 +2488,18 @@ var Users = class {
 	constructor(mailchannels) {
 		this.mailchannels = mailchannels;
 	}
+	/**
+	* Create a recipient user.
+	* @param email - The email address of the user to create.
+	* @param options - The options for the user to create.
+	* @example
+	* ```ts
+	* const mailchannels = new MailChannels('your-api-key')
+	* const { data, error } = await mailchannels.users.create("name@example.com", {
+	*   admin: true
+	* })
+	* ```
+	*/
 	async create(email, options) {
 		const { admin, filter, listEntries } = options || {};
 		let error = null;
@@ -1876,6 +2542,19 @@ var Users = class {
 			error: null
 		};
 	}
+	/**
+	* Add item to recipient user list
+	* @param email - The email address of the recipient whose list will be modified.
+	* @param options - The options for the list entry to add.
+	* @example
+	* ```ts
+	* const mailchannels = new MailChannels('your-api-key')
+	* const { data, error } = await mailchannels.users.addListEntry('name@example.com', {
+	*   listName: 'safelist',
+	*   item: 'name@domain.com'
+	* })
+	* ```
+	*/
 	async addListEntry(email, options) {
 		const { listName, item } = options;
 		let error = null;
@@ -1918,6 +2597,16 @@ var Users = class {
 			error: null
 		};
 	}
+	/**
+	* Get recipient list entries.
+	* @param email - The email address of the recipient whose list will be fetched.
+	* @param listName - The name of the list to fetch. This can be a `blocklist`, `safelist`, `blacklist`, or `whitelist`.
+	* @example
+	* ```ts
+	* const mailchannels = new MailChannels('your-api-key')
+	* const { data, error } = await mailchannels.users.listEntries('name@example.com', 'safelist')
+	* ```
+	*/
 	async listEntries(email, listName) {
 		let error = null;
 		if (!email) {
@@ -1956,6 +2645,19 @@ var Users = class {
 			error: null
 		};
 	}
+	/**
+	* Delete item from recipient list.
+	* @param email - The email address of the recipient whose list will be modified.
+	* @param options - The options for the list entry to delete.
+	* @example
+	* ```ts
+	* const mailchannels = new MailChannels('your-api-key')
+	* const { success, error } = await mailchannels.users.deleteListEntry('name@example.com', {
+	*   listName: 'safelist',
+	*   item: 'name@domain.com'
+	* })
+	* ```
+	*/
 	async deleteListEntry(email, options) {
 		const { listName, item } = options;
 		let error = null;
@@ -1994,6 +2696,14 @@ var Service = class {
 	constructor(mailchannels) {
 		this.mailchannels = mailchannels;
 	}
+	/**
+	* Retrieve the condition of the service
+	* @example
+	* ```ts
+	* const mailchannels = new MailChannels('your-api-key')
+	* const { success, error } = await mailchannels.service.status()
+	* ```
+	*/
 	async status() {
 		let error = null;
 		await this.mailchannels.get("/inbound/v1/status", { onResponseError: async ({ response }) => {
@@ -2006,6 +2716,14 @@ var Service = class {
 			error
 		};
 	}
+	/**
+	* Get a list of your subscriptions to MailChannels Inbound
+	* @example
+	* ```ts
+	* const mailchannels = new MailChannels('your-api-key')
+	* const { data, error } = await mailchannels.service.subscriptions()
+	* ```
+	*/
 	async subscriptions() {
 		let error = null;
 		const response = await this.mailchannels.get("/inbound/v1/subscriptions", { onResponseError: async ({ response }) => {
@@ -2023,6 +2741,17 @@ var Service = class {
 			error: null
 		};
 	}
+	/**
+	* Submit a false negative or false positive report.
+	* @param options - The report options
+	* @example
+	* ```ts
+	* const mailchannels = new MailChannels('your-api-key')
+	* const { success, error } = await mailchannels.service.report({
+	* // ...
+	* })
+	* ```
+	*/
 	async report(options) {
 		let error = null;
 		const { type, ...payload } = options;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mailchannels-sdk",
-  "version": "0.7.4",
+  "version": "0.7.5",
   "description": "Node.js SDK to integrate MailChannels API into your JavaScript or TypeScript server-side applications.",
   "type": "module",
   "license": "MIT",
@@ -37,14 +37,14 @@
     "ofetch": "^2.0.0-alpha.3"
   },
   "devDependencies": {
-    "@stylistic/eslint-plugin": "^5.8.0",
+    "@stylistic/eslint-plugin": "^5.9.0",
     "@types/markdown-it": "^14.1.2",
-    "@types/node": "^25.2.3",
+    "@types/node": "^25.3.0",
     "@vitest/coverage-v8": "^4.0.18",
     "changelogen": "^0.6.2",
     "jiti": "^2.6.1",
-    "obuild": "^0.4.27",
-    "oxlint": "^1.47.0",
+    "obuild": "^0.4.31",
+    "oxlint": "^1.50.0",
     "scule": "^1.3.0",
     "typescript": "^5.9.3",
     "vitepress": "^2.0.0-alpha.16",