nuxt-mailchannels

Simple MailChannels Email API integration for Nuxt

0 downloads•12 stars•v0.4.2

yizack

nuxt-mailchannels

Nuxt MailChannels

Simple MailChannels Email Send API integration for Nuxt.

Leverages mailchannels-sdk package, a MailChannels SDK for Node.js.

Features
Requirements
Quick setup
Configuration
Server utils
- TypeScript signature
- Simple usage
Send method
Examples

Features

Send emails using MailChannels Email Send API
Works on the edge
Exposed server utils
Email DKIM signing
Default global settings
Supports mustache templates
Text and HTML content types

Requirements

Nuxt 3 or higher
MailChannels account and Email API key

!WARNING This module only works with a Nuxt server running as it uses utils for server API routes (nuxt build). This means that you cannot use this module with nuxt generate.

Quick setup

Add nuxt-mailchannels dependency to your project

npx nuxi@latest module add mailchannels

Add the module in your nuxt.config.ts

export default defineNuxtConfig({
  modules: [
    'nuxt-mailchannels'
  ],
})

Configuration

You can add the MailChannels API key and DKIM settings to the runtimeConfig property in nuxt.config.ts file.

If you want to use default global settings for all your email transactions, you can set it in the mailchannels app options property in your nuxt.config.ts file.

export default defineNuxtConfig({
  // Runtime config
  runtimeConfig: {
    mailchannels: {
      apiKey: '',
      dkim: {
        domain: '',
        privateKey: '',
        selector: '',
      },
    },
  },
  // Set the default settings for all your email transactions (optional)
  mailchannels: {
    bcc: { email: '', name: '' },
    cc: { email: '', name: '' },
    from: { email: '', name: '' },
    to: { email: '', name: '' },
  },
})

!NOTEbcc, cc, and to can be an object with email and name properties or a single email address string or an array of them.

Use the environment variables to set your API key, DKIM settings and default global settings.

# Runtime config
NUXT_MAILCHANNELS_API_KEY=

NUXT_MAILCHANNELS_DKIM_DOMAIN=
NUXT_MAILCHANNELS_DKIM_PRIVATE_KEY=
NUXT_MAILCHANNELS_DKIM_SELECTOR=

# App config (optional)

# NUXT_MAILCHANNELS_BCC=
NUXT_MAILCHANNELS_BCC_EMAIL=
NUXT_MAILCHANNELS_BCC_NAME=

# NUXT_MAILCHANNELS_CC=
NUXT_MAILCHANNELS_CC_EMAIL=
NUXT_MAILCHANNELS_CC_NAME=

# NUXT_MAILCHANNELS_FROM=
NUXT_MAILCHANNELS_FROM_EMAIL=
NUXT_MAILCHANNELS_FROM_NAME=

# NUXT_MAILCHANNELS_TO=
NUXT_MAILCHANNELS_TO_EMAIL=
NUXT_MAILCHANNELS_TO_NAME=

!NOTE Setting environment variables will override the settings in nuxt.config.ts file.

Server utils

The following helpers are auto-imported in your server/ directory.

// initialize a MailChannels instance
const mailchannels = useMailChannels(event)

TypeScript signature

const useMailChannels: (event?: H3Event) => {
  send: (options: MailChannelsEmailOptions, dryRun?: boolean) => Promise<EmailsSendResponse>
  queue: (options: MailChannelsEmailOptions) => Promise<EmailsQueueResponse>
}

Simple usage

const mailchannels = useMailChannels(event)
await mailchannels.send({
  from: {
    email: 'from@example.com',
    name: 'Example 2'
  },
  to: {
    email: 'to@example.com',
    name: 'Example 1'
  },
  subject: 'Your subject',
  html: '<p>Your email content</p>',
  text: 'Your email content',
})

Send method

The send method sends an email using the MailChannels API.

!IMPORTANT If you set the bcc, cc, from, to properties in the send method, they will override the default global settings set in the nuxt.config.ts or .env file.

Arguments

Argument	Type	Description	Required
`options`	`Options`	The email options to send	✅
`dryRun`	`boolean`	When set to `true`, the message will not be sent. Instead, the fully rendered message will be returned in the `data` property of the response. The default value is `false`.	❌

Options

Available options for the send method.

Property	Description	Required
`attachments`	An array of attachments to add to the email. Each attachment should be an object with `filename`, `content`, and `type` properties.	❌
`campaignId`	The campaign identifier. If specified, this ID will be included in all relevant webhooks. It can be up to 48 UTF-8 characters long and must not contain spaces.	❌
`bcc`	The BCC recipients of the email. Can be an object with `email` and `name` properties or a single email address string or an array of them.	❌
`dkim`	The DKIM settings for the email.	❌
`envelopeFrom`	Optional envelope sender address. If not set, the envelope sender defaults to the `from.email` field. Can be overridden per-personalization. Only the email portion is used; the name field is ignored.	❌
`cc`	The CC recipients of the email. Can be an object with `email` and `name` properties or a single email address string or an array of them.	❌
`from`	The sender of the email. Can be a string or an object with `email` and `name` properties. Required when the default global sender is not set.	🟡
`headers`	An object containing key-value pairs, where both keys (header names) and values must be strings. These pairs represent custom headers to be substituted.	❌
`to`	The recipient of the email. Can be an object with `email` and `name` properties or a single email address string or an array of them. Required when the default global recipient is not set.	🟡
`tracking`	Adjust open and click tracking for the message.	❌
`replyTo`	The email address to reply to. Can be a string or an object with `email` and `name` properties.	❌
`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.	🟡
`content`	Send the body of your message in multiple different formats. The recipient's email client will render the message using the content type that best fits their environment.	❌
`template`	Template configuration for rendering email content with a template engine.	❌
`personalizations`	Explicit personalization objects for advanced payloads with multiple recipient groups or per-personalization overrides.	❌
`transactional`	Mark these messages as transactional or non-transactional. In order for a message to be marked as non-transactional, it must have exactly one recipient per personalization, and it must be DKIM signed. 400 Bad Request will be returned if there are more than one recipient in any personalization for non-transactional messages. If a message is marked as non-transactional, it changes the sending process as follows: List-Unsubscribe headers will be added.	❌

More details about the options can be found in the MailChannels Node.js SDK documentation.

!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.

Response

The send method returns a promise that resolves to an object with the following properties.

Property	Type	Description
`data`	`EmailsSendResponse["data"]` or `null`	Read more in the MailChannels Node.js SDK documentation
`error`	`ErrorResponse` or `null`	Contains error information if the email sending operation fails.

Queue method

The queue method queues an email message for asynchronous processing and returns immediately with a request ID.

Use this method when you need to send emails without waiting for processing to complete. This can improve your application's response time, especially when sending to multiple recipients.

Arguments

Argument	Type	Description	Required
`options`	`Options`	The email options to send	✅

Options

The options for the queue method are the same as the send method.

Response

Property	Type	Description
`data`	`EmailsQueueResponse["data"]` or `null`	Read more in the MailChannels Node.js SDK documentation
`error`	`ErrorResponse` or `null`	Contains error information if the email sending operation fails.

Examples

Use the send method inside your API routes to send emails.

The recipient parameters can be either an email address string or an object with email and name properties.

Using object recipients (recommended)

This is the best way to add names to the recipients.

export default defineEventHandler(async (event) => {
  const mailchannels = useMailChannels(event)

  const { data, error } = await mailchannels.send({
    from: {
      email: 'from@example.com',
      name: 'Example 2'
    },
    to: {
      email: 'to@example.com',
      name: 'Example 1'
    },
    subject: 'Your subject',
    html: '<p>Your email content</p>',
    text: 'Your email content'
  })

  return { data }
})

Using string recipients

This is the simplest way to send an email.

export default defineEventHandler(async (event) => {
  const mailchannels = useMailChannels(event)

  const { data, error } = await mailchannels.send({
    from: 'from@example.com',
    to: 'to@example.com',
    subject: 'Your subject',
    html: '<p>Your email content</p>',
    text: 'Your email content'
  })

  return { data }
})

Array of recipients

You can also send an email to multiple recipients.

export default defineEventHandler(async (event) => {
  const mailchannels = useMailChannels(event)

  const { data, error } = await mailchannels.send({
    from: {
      email: 'from@example.com',
      name: 'Example 3'
    },
    to: [
      {
        email: 'to1@example.com',
        name: 'Example 1'
      },
      {
        email: 'to2@example.com',
        name: 'Example 2'
      }
    ],
    subject: 'Your subject',
    html: '<p>Your email content</p>',
    text: 'Your email content'
  })

  return { data }
})

export default defineEventHandler(async (event) => {
  const mailchannels = useMailChannels(event)

  const { data, error } = await mailchannels.send({
    from: 'from@example.com',
    to: ['to1@example.com', 'to2@example.com'],
    subject: 'Your subject',
    html: '<p>Your email content</p>',
    text: 'Your email content'
  })

  return { data }
})

Using mustache templates

You can use the template property to render mustache templates.

export default defineEventHandler(async (event) => {
  const mailchannels = useMailChannels(event)

  const { data, error } = await mailchannels.send({
    from: 'from@example.com',
    to: 'to@example.com',
    subject: 'Mustaches test',
    html: '<p>Hello {{ world }}</p>',
    text: 'Hello {{ world }}',
    template: {
      type: 'mustache',
      data: {
        world: 'World'
      }
    }
  })

  return { data }
})

Dry run

You can set the dryRun argument to test your email without sending it. It will return the fully rendered message in the data.rendered property of the response.

export default defineEventHandler(async (event) => {
  const mailchannels = useMailChannels(event)

  const { data, error } = await mailchannels.send({
    from: 'from@example.com',
    to: 'to@example.com',
    subject: 'Test',
    html: '<p>Test</p>',
    text: 'Test',
  }, true) // <-- `true` = dryRun enabled

  return { data }
})

Name-address pairs

You can use name-address pairs string format.

export default defineEventHandler(async (event) => {
  const mailchannels = useMailChannels(event)

  const { data, error } = await mailchannels.send({
    from: 'Sender Name <sender@example.com>',
    to: 'Recipient Name <recipient@example.com>',
    subject: 'Your subject',
    html: '<p>Your email content</p>',
    text: 'Your email content',
  })

  return { data }
})

Async sending

You can use the queue method to queue an email message for asynchronous processing.

export default defineEventHandler(async (event) => {
  const mailchannels = useMailChannels(event)

  const { data, error } = await mailchannels.queue({
    from: {
      email: 'from@example.com',
      name: 'Example 2'
    },
    to: {
      email: 'to@example.com',
      name: 'Example 1'
    },
    subject: 'Your subject',
    html: '<p>Your email content</p>',
    text: 'Your email content',
  })

  return { data }
})

Contribution

Local development

# Install dependencies
npm install

# Generate type stubs
pnpm dev:prepare

# Develop with the playground
pnpm dev

# Build the playground
pnpm dev:build

# Run ESLint
pnpm lint

# Run Vitest
pnpm test
pnpm test:watch

# Run typecheck
pnpm test:types

# Release new version
pnpm release