📧 Emails module

This module allows you to send emails and check domain settings for secure email delivery.

Send method

Sends an email message to one or more recipients.

Usage

modular.ts

import { MailChannelsClient } from '@yizack/mailchannels'
import { Emails } from '@yizack/mailchannels/modules'

const mailchannels = new MailChannelsClient('your-api-key')
const emails = new Emails(mailchannels)

const { success } = await emails.send({
  from: '[email protected]',
  to: '[email protected]',
  subject: 'Your subject',
  html: '<p>Your email content</p>',
  text: 'Your email content',
})

full.ts

import { MailChannels } from '@yizack/mailchannels'
const mailchannels = new MailChannels('your-api-key')

const { success } = await mailchannels.emails.send({
  from: '[email protected]',
  to: '[email protected]',
  subject: 'Your subject',
  html: '<p>Your email content</p>',
  text: 'Your email content',
})

Params

• options: Send options.
  • attachments: An array of attachments to be sent with the email.
    • content: The attachment data, encoded in base64
    • filename: The name of the attachment file
    • type: The MIME type of the attachment
  • bcc: The BCC recipients of the email.
  • cc: The CC recipients of the email.
  • dkim: The DKIM settings for the email.
    • domain: The domain to sign the email with.
    • privateKey: The private key to sign the email with.
    • selector: The DKIM selector to use.
  • from: The sender of the email.
  • to: The recipients of the email.
  • tracking Adjust open and click tracking for the message.

    INFO

    Tracking for your messages requires a subscription that supports open and click tracking.

    Only links (<a> tags) meeting all of the following conditions are processed for click tracking:

    • The URL is non-empty.
    • The URL starts with http or https.
    • The link does not have a clicktracking attribute set to off.
  • replyTo: The reply-to address of the email.
  • subject: The subject of the email.
  • html: The HTML content of the email. Required if text is not set.
  • text: The plain text content of the email. Required if html is not set.

    IMPORTANT

    Either html or text must be provided.

    TIP

    Including a plain text version of your email ensures that all recipients can read your message, including those with email clients that lack HTML support.

    You can use the html-to-text package to convert your HTML content to plain text.

  • mustaches: Data to be used if the email is a mustache template, key-value pairs of variables to set for template rendering.
• dryRun: When set to true, the email will not be sent. Instead, the fully rendered message will be returned in the data property of the response.

  TIP

  Use dryRun to test your email message before sending it.

Check Domain method

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 } from '@yizack/mailchannels'
import { Emails } from '@yizack/mailchannels/modules'

const mailchannels = new MailChannelsClient('your-api-key')
const emails = new Emails(mailchannels)

const { results } = await emails.checkDomain({
  domain: 'example.com',
  dkim: {
    domain: 'example.com',
    selector: 'your-dkim-selector',
    privateKey: 'your-dkim-private-key'
  },
  senderId: 'your-sender-id'
});

full.ts

import { MailChannels } from '@yizack/mailchannels'
const mailchannels = new MailChannels('your-api-key')

const { success } = await mailchannels.emails.checkDomain({
  domain: 'example.com',
  dkim: {
    domain: 'example.com',
    selector: 'your-dkim-selector',
    privateKey: 'your-dkim-private-key'
  },
  senderId: 'your-sender-id'
});

Params

• options: Check domain options.
  • dkim: The DKIM settings for the domain.
    • domain: The DKIM domain to sign the email with.
    • privateKey: The DKIM private key to sign the email with. Encoded in Base64.
    • selector: The DKIM selector to use.
  • domain: Domain used for sending emails.
  • senderId: The sender ID to check the domain with.

    INFO

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

Type declarations

class Emails {
  constructor (protected mailchannels: MailChannelsClient) {}
  async send (options: EmailsSendOptions, dryRun = false): Promise<EmailsSendResponse>;
  async checkDomain (options: EmailsCheckDomainOptions): Promise<EmailsCheckDomainResponse>;
}

All type declarations

Send type declarations

type EmailsSendOptions = EmailsSendOptionsBase & (
  | {
    html: string;
    text?: string;
  }
  | {
    html?: string;
    text: string;
  }
);

interface EmailsSendOptionsBase {
  attachments?: EmailsSendAttachment[];
  bcc?: EmailsSendRecipient[] | EmailsSendRecipient | string[] | string;
  cc?: EmailsSendRecipient[] | EmailsSendRecipient | string[] | string;
  dkim?: {
    domain: string;
    privateKey: string;
    selector: string;
  };
  from: EmailsSendRecipient | string;
  to: EmailsSendRecipient[] | EmailsSendRecipient | string[] | string;
  tracking?: EmailsSendTracking;
  replyTo?: EmailsSendRecipient | string;
  subject: string;
  mustaches?: Record<string, unknown>;
}

interface EmailsSendAttachment {
  content: string;
  filename: string;
  type: string;
}

interface EmailsSendRecipient {
  email: string;
  name?: string;
}

interface EmailsSendTracking {
  click?: boolean;
  open?: boolean;
}

interface EmailsSendResponse {
  success: boolean;
  data: string[] | undefined;
}

Check Domain type declarations

interface EmailsCheckDomainOptions {
  dkim: EmailsCheckDomainDkim[] | EmailsCheckDomainDkim;
  domain: string;
  senderId: string;
}

interface EmailsCheckDomainResponse {
  results: {
    dkim: {
      domain: string;
      selector: string;
      reason?: string;
      verdict: Extract<EmailsCheckDomainVerdict, "passed" | "failed">;
    }[];
    domainLockdown: {
      reason?: string;
      verdict: Extract<EmailsCheckDomainVerdict, "passed" | "failed">;
    };
    spf: {
      reason?: string;
      verdict: EmailsCheckDomainVerdict;
    };
  };
  references?: string[];
}

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

interface EmailsCheckDomainDkim {
  domain: string;
  privateKey: string;
  selector: string;
}

Source

Source