Rotate DKIM Key method 🌐 Domains

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.

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.dkim.rotate('example.com', 'mailchannels', {
  newKey: {
    selector: 'new-selector'
  }
})

full.ts

import { MailChannels } from 'mailchannels-sdk'

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

const { data, error } = await mailchannels.domains.dkim.rotate('example.com', 'mailchannels', {
  newKey: {
    selector: 'new-selector'
  }
})

Params

• domain string required: The domain the DKIM key belongs to.
• selector string required: The selector of the DKIM key to rotate. Must be a maximum of 63 characters.
• options object required: The options to rotate the DKIM key.
  • newKey object required: New DKIM key options.
    • selector string required: The selector for the new key pair. Must be a maximum of 63 characters.

Response

• data object | null nullable: The rotated and new DKIM key information.
  • new DomainsDkimKey guaranteed
    • algorithm string guaranteed: Algorithm used for the key pair.
    • createdAt string optional: Timestamp when the key pair was created.
    • dnsRecords object[] guaranteed: Suggested DNS records for the DKIM key.
      • name string guaranteed
      • type string guaranteed
      • value string guaranteed
    • domain string guaranteed: Domain associated with the key pair.
    • gracePeriodExpiresAt string optional: UTC timestamp after which you can no longer use the rotated key for signing.
    • length 1024 | 2048 | 3072 | 4096 guaranteed: Key length in bits.
    • publicKey string guaranteed
    • retiresAt string optional: UTC timestamp when a rotated key pair is retired.
    • selector string guaranteed: Selector assigned to the key pair.
    • status "active" | "revoked" | "retired" | "rotated" guaranteed: Status of the key.
    • statusModifiedAt string optional: Timestamp when the key was last modified.
  • rotated DomainsDkimKey guaranteed
    • algorithm string guaranteed: Algorithm used for the key pair.
    • createdAt string optional: Timestamp when the key pair was created.
    • dnsRecords object[] guaranteed: Suggested DNS records for the DKIM key.
      • name string guaranteed
      • type string guaranteed
      • value string guaranteed
    • domain string guaranteed: Domain associated with the key pair.
    • gracePeriodExpiresAt string optional: UTC timestamp after which you can no longer use the rotated key for signing.
    • length 1024 | 2048 | 3072 | 4096 guaranteed: Key length in bits.
    • publicKey string guaranteed
    • retiresAt string optional: UTC timestamp when a rotated key pair is retired.
    • selector string guaranteed: Selector assigned to the key pair.
    • status "active" | "revoked" | "retired" | "rotated" guaranteed: Status of the key.
    • statusModifiedAt string optional: Timestamp when the key was last modified.
• 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.

Type declarations

Signature

async function rotate (domain: string, selector: string, options: DomainsDkimRotateOptions): Promise<DomainsDkimRotateResponse>

Response type declarations

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

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

DKIM key type declarations

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

Rotate DKIM Key type declarations

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

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

Source

Source • Playground • Docs • Tests