mailchannels-sdk 1.1.0 → 1.3.0

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.
@@ -1246,8 +1440,15 @@ interface SubAccountsUsage {
   startDate?: string;
   /**
    * The total usage for the current billing period.
+   * @example 5000
    */
   total: number;
+  /**
+   * The effective monthly limit for the current billing period. A limit of zero means the account cannot send any messages.
+   * For sub-accounts with no explicit limit set (i.e., -1), the monthly limit for the parent account is returned.
+   * @example 10000
+   */
+  monthlyLimit: number;
 }
 type SubAccountsUsageResponse = DataResponse<SubAccountsUsage>;
 interface MetricsEngagement {
@@ -1259,25 +1460,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[];
   };
@@ -1369,8 +1619,15 @@ type MetricsUsageResponse = DataResponse<{
   startDate?: string;
   /**
    * The total usage for the current billing period.
+   * @example 5000
    */
   total: number;
+  /**
+   * The effective monthly limit for the current billing period. A limit of zero means the account cannot send any messages.
+   * For sub-accounts with no explicit limit set (i.e., -1), the monthly limit for the parent account is returned.
+   * @example 10000
+   */
+  monthlyLimit: number;
 }>;
 type MetricsSendersType = "sub-accounts" | "campaigns";
 interface MetricsSendersOptions {
@@ -1453,6 +1710,21 @@ interface MetricsOptions {
   interval?: "hour" | "day" | "week" | "month";
 }
 type SuppressionsTypes = "transactional" | "non-transactional";
+interface SuppressionsCreateEntry {
+  /**
+   * Must be less than `1024` characters.
+   */
+  notes?: string;
+  /**
+   * The email address to suppress. Must be a valid email address format and less than `255` characters.
+   */
+  recipient: string;
+  /**
+   * An array of types of suppression to apply to the recipient.
+   * @default ["non-transactional"]
+   */
+  types?: SuppressionsTypes[];
+}
 interface SuppressionsCreateOptions {
   /**
    * If true, the parent account creates suppression entries for all associated sub-accounts. This field is only applicable to parent accounts. Sub-accounts cannot create entries for other sub-accounts.
@@ -1461,22 +1733,9 @@ interface SuppressionsCreateOptions {
   addToSubAccounts?: boolean;
   /**
    * The total number of suppression entries to create, for the parent and/or its sub-accounts, must not exceed `1000`.
+   * @deprecated Use `create(entries, options?)` instead.
    */
-  entries: {
-    /**
-     * Must be less than `1024` characters.
-     */
-    notes?: string;
-    /**
-     * The email address to suppress. Must be a valid email address format and less than `255` characters.
-     */
-    recipient: string;
-    /**
-     * An array of types of suppression to apply to the recipient.
-     * @default ["non-transactional"]
-     */
-    types?: SuppressionsTypes[];
-  }[];
+  entries: SuppressionsCreateEntry[];
 }
 type SuppressionsSource = "api" | "unsubscribe_link" | "list_unsubscribe" | "hard_bounce" | "spam_complaint" | "all";
 interface SuppressionsListOptions {
@@ -1727,7 +1986,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
@@ -1782,14 +2041,21 @@ declare class Suppressions {
   constructor(mailchannels: MailChannelsClient);
   /**
    * 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.
+   * @param entries - The total number of suppression entries to create, for the parent and/or its sub-accounts, must not exceed `1000`.
+   * @param options - The options of the suppression entries to create.
    * @example
    * ```ts
    * const mailchannels = new MailChannels('your-api-key')
-   * const { success, error } = await mailchannels.suppressions.create({
-   * // ...
-   * });
+   * const { success, error } = await mailchannels.suppressions.create([
+   *   {
+   *     notes: "test",
+   *     recipient: "name@example.com",
+   *     types: ["transactional"]
+   *   }
+   * ], { addToSubAccounts: false });
    */
+  create(entries: SuppressionsCreateEntry[], options?: Omit<SuppressionsCreateOptions, "entries">): Promise<SuccessResponse>;
+  /** @deprecated Use positional params `create(entries, options?)` instead. */
   create(options: SuppressionsCreateOptions): Promise<SuccessResponse>;
   /**
    * Deletes suppression entry associated with the account based on the specified recipient and source.
@@ -1827,4 +2093,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 SuppressionsCreateEntry, 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 };