Update Custom Tracking Domain method 🌐 Domains

Update an existing custom tracking domain by its hostname and scope. Supports updating the custom tracking domain's name or toggling its active status.

Usage

modular.ts

import { MailChannelsClient, Domains } from 'mailchannels-sdk'

const mailchannels = new MailChannelsClient('your-api-key')
const domains = new Domains(mailchannels)

const { data, error } = await domains.customTracking.update('click.example.com', 'click', {
  name: 'newclickname',
  status: 'active'
})

if (error) {
  throw new Error(error.message)
}

if (data.dnsSetupRequired) {
  // DNS setup required fields available here
}
else {
  // Domain fields available here
}

full.ts

import { MailChannels } from 'mailchannels-sdk'

const mailchannels = new MailChannels('your-api-key')

const { data, error } = await mailchannels.domains.customTracking.update('click.example.com', 'click', {
  name: 'newclickname',
  status: 'active'
})

if (error) {
  throw new Error(error.message)
}

if (data.dnsSetupRequired) {
  // DNS setup required fields available here
}
else {
  // Domain fields available here
}

Params

• hostname string required: The hostname of the custom tracking domain to update.
• scope DomainsCustomTrackingScope required: The scope of the custom tracking domain to update (click, open, unsubscribe).
• options DomainsCustomTrackingUpdateOptions required: The options for updating the custom tracking domain.
  • name string optional: New label for this custom tracking domain.

    IMPORTANT

    Maximum length is 64 characters. Must match the pattern ^[a-z0-9-]+$.

  • status "active" | "disabled" optional: New status. Re-activation requires DNS verification — add the TXT record and CNAME record described in the response body, then retry.

Response

• data DomainsCustomTrackingWithDnsSetupRequired | null nullable: The updated domain or DNS verification info when pending.
  • When DNS setup is complete:
    • dnsSetupRequired false guaranteed: Whether DNS setup is required for this domain.
    • name string guaranteed: The label for this custom tracking domain.
    • hostname string guaranteed: The registered domain hostname.
    • scope DomainsCustomTrackingScope guaranteed: The event type this domain handles (click, open, unsubscribe).
    • status "active" | "disabled" guaranteed: Current status of the custom tracking domain.
    • createdAt string guaranteed: ISO 8601 timestamp when the domain was registered.
  • When DNS setup is required:
    • dnsSetupRequired true guaranteed: Whether DNS setup is required for this domain.
    • token string optional: UUID v4 nonce; also the TXT record value to set. Present only when TXT ownership verification is pending.
    • txtRecordName string optional: Fully-qualified DNS TXT record name to add. Present only when TXT ownership verification is pending.
    • txtRecordValue string optional: Value for the DNS TXT record. Present only when TXT ownership verification is pending.
    • instructions string optional: Human-readable guidance for the DNS records that must be in place before retrying.
• error ErrorResponse | null nullable: Error information if the operation failed.
  • message string guaranteed: A human-readable description of the error.
  • statusCode number | null nullable: The HTTP status code from the API, or null if the error is not related to an HTTP request. This field is intended for diagnostic use only and should not be relied upon.
  • type string guaranteed: A string identifier for the type of error. This field is intended for diagnostic use only and should not be relied upon.
  • response Record<string, unknown> | null nullable: 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.

Type declarations

Signature

async function update (hostname: string, scope: DomainsCustomTrackingScope, options: DomainsCustomTrackingUpdateOptions): Promise<DomainsCustomTrackingUpdateResponse>

Response type declarations

interface ErrorResponse {
  message: string;
  statusCode: number | null;
  type: ErrorType;
  response: Record<string, unknown> | null;
}

type DataResponse<T> = {
  data: T;
  error: null;
} | {
  data: null;
  error: ErrorResponse;
};

Custom Tracking Domain type declarations

type DomainsCustomTrackingScope = "click" | "open" | "unsubscribe";

interface DomainsCustomTrackingDomain {
  name: string;
  hostname: string;
  scope: DomainsCustomTrackingScope;
  status: "active" | "disabled";
  createdAt: string;
}

Update Custom Tracking Domain type declarations

interface DomainsCustomTrackingUpdateOptions {
  name?: string;
  status?: "active" | "disabled";
}

interface DomainsCustomTrackingDnsSetupRequired {
  token?: string;
  txtRecordName?: string;
  txtRecordValue?: string;
  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 DomainsCustomTrackingUpdateResponse = DataResponse<DomainsCustomTrackingWithDnsSetupRequired>;

Source

Source • Playground • Docs • Tests