🌐 Domains module Email API

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

Methods

• Check Domain
• Create DKIM Key
• List DKIM Keys
• Update DKIM Key Status
• Rotate DKIM Key

Type declarations

class Domains {
  readonly dkim: DomainsDkim;
  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>;
}

All type declarations

Response type declarations

interface ErrorResponse {
  message: string;
  statusCode: number | null;
  type: ErrorType;
}

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

Source

Source • Playground • Docs • Tests

Changelog

• Unreleased 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