nuxt-mailchannels v0.1.10

Nuxt MailChannels

Simple MailChannels Email API integration for Nuxt.

• ✨ Release Notes
• 🏀 Online playground

Contents

• Features
• Requirements
• Quick setup
• Configuration
• Server utils
  • TypeScript signature
  • Simple usage
• Send method
  • Arguments
  • Options
  • Response
• Examples
  • Using object recipients (recommended)
  • Using string recipients
  • Array of recipients
  • Mustache templates
  • Dry run
  • Name-address pairs

Features

• Send emails using MailChannels Email 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

1. Add nuxt-mailchannels dependency to your project

pnpm add nuxt-mailchannels -D

2. 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: '' },
  },
})

!NOTE bcc, 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=

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<{
    success: boolean,
    payload: MailChannelsEmailPayload,
    data: string[] | undefined,
  }>
}

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

Options

Available options for the send method.

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

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 { success } = 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 { success }
})

Using string recipients

This is the simplest way to send an email.

export default defineEventHandler(async (event) => {
  const mailchannels = useMailChannels(event)
  const { success } = 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 { success }
})

Array of recipients

You can also send an email to multiple recipients.

export default defineEventHandler(async (event) => {
  const mailchannels = useMailChannels(event)
  const { success } = 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 { success }
})

or

export default defineEventHandler(async (event) => {
  const mailchannels = useMailChannels(event)
  const { success } = 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 { success }
})

Using mustache templates

You can use the mustaches property to render mustache templates.

export default defineEventHandler(async (event) => {
  const mailchannels = useMailChannels(event)
  const { success } = await mailchannels.send({
    from: 'from@example.com',
    to: 'to@example.com',
    subject: 'Mustaches test',
    html: '<p>Hello {{ world }}</p>',
    text: 'Hello {{ world }}',
    mustaches: {
      world: 'World',
    },
  })

  return { success }
})

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 property of the response.

export default defineEventHandler(async (event) => {
  const mailchannels = useMailChannels(event)
  const response = await mailchannels.send({
    from: 'from@example.com',
    to: 'to@example.com',
    subject: 'Test',
    html: '<p>Test</p>',
    text: 'Test',
  }, true) // <-- `true` = dryRun enabled

  return response
})

Name-address pairs

You can use name-address pairs string format.

export default defineEventHandler(async (event) => {
  const mailchannels = useMailChannels(event)
  const { success } = 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 { success }
})

Contribution

Generate type stubs

npm run dev:prepare

Develop with the playground

npm run dev

Build the playground

npm run dev:build

Run ESLint

npm run lint

Run Vitest

npm run test npm run test:watch

Run typecheck

npm run test:types

Release new version

npm run release

</details>

<!-- Badges -->
[npm-version-src]: https://img.shields.io/npm/v/nuxt-mailchannels/latest.svg?style=flat&colorA=020420&colorB=00DC82
[npm-version-href]: https://npmjs.com/package/nuxt-mailchannels

[npm-downloads-src]: https://img.shields.io/npm/dm/nuxt-mailchannels.svg?style=flat&colorA=020420&colorB=00DC82
[npm-downloads-href]: https://npmjs.com/package/nuxt-mailchannels

[license-src]: https://img.shields.io/npm/l/nuxt-mailchannels.svg?style=flat&colorA=020420&colorB=00DC82
[license-href]: LICENSE

[nuxt-src]: https://img.shields.io/badge/Nuxt-020420?logo=nuxt.js
[nuxt-href]: https://nuxt.com

[modules-src]: https://img.shields.io/badge/Modules-020420?logo=nuxt.js
[modules-href]: https://nuxt.com/modules/mailchannels