🌐 Domains module Email API

This module allows you to check a domain's email authentication, manage DKIM keys for secure email delivery, and manage custom tracking domains.

Methods

• Check Domain
• Create DKIM Key
• List DKIM Keys
• Update DKIM Key Status
• Rotate DKIM Key
• Create Custom Tracking Domain
• List Custom Tracking Domains
• Delete Custom Tracking Domain
• Update Custom Tracking Domain

Type declarations

class Domains {
  readonly dkim: DomainsDkim;
  readonly customTracking: DomainsCustomTracking;
  constructor (protected mailchannels: MailChannelsClient);
  async check (domain: string, options?: DomainsCheckOptions): Promise<DomainsCheckResponse>;
}

class DomainsDkim {
  constructor (private mailchannels: MailChannelsClient);
  async create (domain: string, options: DomainsDkimCreateOptions): Promise<DomainsDkimCreateResponse>;
  async list (domain: string, options?: DomainsDkimListOptions): Promise<DomainsDkimListResponse>;
  async updateStatus (domain: string, options: DomainsDkimUpdateStatusOptions): Promise<SuccessResponse>;
  async rotate (domain: string, selector: string, options: DomainsDkimRotateOptions): Promise<DomainsDkimRotateResponse>;
}

class DomainsCustomTracking {
  constructor (private mailchannels: MailChannelsClient);
  async list (options?: DomainsCustomTrackingListOptions): Promise<DomainsCustomTrackingListResponse>;
  async create (name: string, hostname: string, scope: DomainsCustomTrackingScope): Promise<DomainsCustomTrackingCreateResponse>;
  async update (hostname: string, scope: DomainsCustomTrackingScope, options: DomainsCustomTrackingUpdateOptions): Promise<DomainsCustomTrackingUpdateResponse>;
  async delete (hostname: string, scope: DomainsCustomTrackingScope): Promise<SuccessResponse>;
}

All type declarations

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;
};

interface SuccessResponse {
  success: boolean;
  error: ErrorResponse | null;
}

Domain check type declarations

interface DomainsCheck {
  domain?: string;
  privateKey?: string;
  selector?: string;
}

interface DomainsCheckOptions {
  dkim?: DomainsCheck[] | DomainsCheck;
  senderId?: string;
}

type DomainsCheckVerdict = "passed" | "failed" | "soft failed" | "temporary error" | "permanent error" | "neutral" | "none" | "unknown";

type DomainsCheckResponse = DataResponse<{
  dkim: {
    domain: string;
    keyStatus?: DomainsDkimKey["status"] | "provided";
    selector: string;
    reason?: string;
    verdict: Extract<DomainsCheckVerdict, "passed" | "failed">;
  }[];
  domainLockdown: {
    reason?: string;
    verdict: Extract<DomainsCheckVerdict, "passed" | "failed">;
  };
  senderDomain: {
    a: {
      reason?: string;
      verdict: Extract<DomainsCheckVerdict, "passed" | "failed">;
    };
    mx: {
      reason?: string;
      verdict: Extract<DomainsCheckVerdict, "passed" | "failed">;
    };
    verdict: Extract<DomainsCheckVerdict, "passed" | "failed">;
  };
  spf: {
    reason?: string;
    spfRecord?: string;
    spfRecordError?: string;
    verdict: DomainsCheckVerdict;
  };
  references?: string[];
}>;

Create DKIM Key type declarations

interface DomainsDkimCreateOptions {
  algorithm?: "rsa";
  length?: 1024 | 2048 | 3072 | 4096;
  selector: string;
}

type DomainsDkimKeyStatus = "active" | "retired" | "revoked" | "rotated";

interface DomainsDkimKey {
  algorithm: string;
  createdAt?: string;
  dnsRecords: {
    name: string;
    type: string;
    value: string;
  }[];
  domain: string;
  gracePeriodExpiresAt?: string;
  length: 1024 | 2048 | 3072 | 4096;
  publicKey: string;
  retiresAt?: string;
  selector: string;
  status: DomainsDkimKeyStatus;
  statusModifiedAt?: string;
}

type DomainsDkimCreateResponse = DataResponse<DomainsDkimKey>;

List DKIM Keys type declarations

interface DomainsDkimListOptions {
  selector?: string;
  status?: DomainsDkimKey["status"];
  offset?: number;
  limit?: number;
  includeDnsRecord?: boolean;
}

type Optional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;

type DomainsDkimListResponse = DataResponse<Optional<DomainsDkimKey, "dnsRecords">[]>;

Update DKIM Key type declarations

interface DomainsDkimUpdateStatusOptions {
  selector: string;
  status: Exclude<DomainsDkimKey["status"], "active">;
}

Rotate DKIM Key type declarations

interface DomainsDkimRotateOptions {
  newKey: {
    selector: string;
  };
}

type DomainsDkimRotateResponse = DataResponse<{
  new: DomainsDkimKey;
  rotated: DomainsDkimKey;
}>;

Custom Tracking Domain type declarations

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

interface DomainsCustomTrackingDomain {
  name: string;
  hostname: string;
  scope: DomainsCustomTrackingScope;
  status: "active" | "disabled";
  createdAt: 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 };

Create Custom Tracking Domain type declarations

interface DomainsCustomTrackingDnsSetupRequired {
  token?: string;
  txtRecordName?: string;
  txtRecordValue?: string;
  instructions?: string;
}

type DomainsCustomTrackingCreateResponse = DataResponse<DomainsCustomTrackingWithDnsSetupRequired>;

List Custom Tracking Domains response type declarations

interface DomainsCustomTrackingListOptions {
  name?: string;
  status?: "active" | "disabled";
  scope?: DomainsCustomTrackingScope;
  limit?: number;
  offset?: number;
}

type DomainsCustomTrackingListResponse = DataResponse<{
  customTrackingDomains: DomainsCustomTrackingDomain[];
  total: number;
}>;

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

Changelog

• v1.2.0 on Jul 6, 2026

  • 5f9d0b7 — refactor(domains): replace options object with positional params
  • 7c35915 — feat: add custom tracking domains and update send options

• v1.1.0 on Jun 12, 2026

  • 5a34b8a — fix: encode path params in all api requests
  • b2cf377 — refactor: restructure modules into module directories

• v1.0.0 on May 26, 2026

  • f49c49f — feat(errors): introduce error type keys

• v0.8.0 on May 27, 2026

  • 2d13d37 — refactor(domains-check)!: accept domain as first argument
  • daa8864 — fix: validate domain presence in domain methods
  • ab66dc1 — refactor: split internal utils into focused modules
  • bd4c25f — refactor!: rename webhooks enroll and dkim update methods