Check Domain method 🌐 Domains

DKIM, SPF & Domain Lockdown Check

Validates a domain's email authentication setup by retrieving its DKIM, SPF, and Domain Lockdown status. This method checks whether the domain is properly configured for secure email delivery.

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.check('example.com', {
  dkim: {
    domain: 'example.com',
    selector: 'your-dkim-selector',
    privateKey: 'your-dkim-private-key'
  },
  senderId: 'your-sender-id'
})

full.ts

import { MailChannels } from 'mailchannels-sdk'

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

const { data, error } = await mailchannels.domains.check('example.com', {
  dkim: {
    domain: 'example.com',
    selector: 'your-dkim-selector',
    privateKey: 'your-dkim-private-key'
  },
  senderId: 'your-sender-id'
})

Params

• domain string required: Domain used for sending emails. If dkim settings are not provided, or dkim settings are provided with no domain, the stored dkim settings for this domain will be used.
• options DomainsCheckOptions optional: Check domain options.
  • dkim DomainsCheck[] | DomainsCheck optional: The DKIM settings for the domain.
    • domain string optional: The DKIM domain to sign the email with.
    • privateKey string optional: The DKIM private key to sign the email with. Encoded in Base64.
    • selector string optional: The DKIM selector to use.

    TIP

    The absence or presence of these fields affects how DKIM settings are validated:

    1. If domain, selector, and privateKey are all present, verify using the provided domain, selector, and key.
    2. If domain and selector are present, use the stored private key for the given domain and selector.
    3. If only domain is present, use all stored keys for the given domain.
    4. If none are present, use all stored keys for the domain provided in the domain field of the request.
    5. If privateKey is present, selector must be present.
    6. If selector is present and domain is not, the domain will be taken from the domain field of the request.
  • senderId string optional: Used exclusively for Domain Lockdown verification. If you're not using senderid to associate your domain with your account, you can disregard this field.

    INFO

    Your senderId is the X-MailChannels-Sender-Id header value in emails sent via MailChannels.

Response

• data object | null nullable: The results of the domain checks.
  • dkim object[] guaranteed
    • domain string guaranteed
    • keyStatus "active" | "revoked" | "retired" | "provided" | "rotated" guaranteed: The human readable status of the DKIM key used for verification.
    • selector string guaranteed
    • reason string optional: A human-readable explanation of DKIM check.
    • verdict "passed" | "failed" guaranteed
  • domainLockdown object guaranteed
    • reason string optional: A human-readable explanation of Domain Lockdown check.
    • verdict "passed" | "failed" guaranteed
  • senderDomain object guaranteed: These results are here to help avoid SDNF (Sender Domain Not Found) blocks. For messages not to get blocked by SDNF, we require either an MX or A record to exist for the sender domain.
    • a object guaranteed
      • reason string optional: A human-readable explanation of A record check.
      • verdict "passed" | "failed" guaranteed
    • mx object guaranteed
      • reason string optional: A human-readable explanation of MX record check.
      • verdict "passed" | "failed" guaranteed
  • spf object guaranteed
    • reason string optional: A human-readable explanation of SPF check.
    • spfRecord string optional: The SPF record that was used for the check.
    • spfRecordError string optional: Error message if the SPF record lookup failed.
    • verdict "passed" | "failed" | "soft failed" | "temporary error" | "permanent error" | "neutral" | "none" | "unknown" guaranteed
  • references string[] optional
• 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 check (domain: string, options?: DomainsCheckOptions): Promise<DomainsCheckResponse>

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

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

Check Domain 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[];
}>;

Source

Source • Playground • Docs • Tests