nuxt-mailchannels

Simple MailChannels Email API integration for Nuxt

343 downloads•11 stars•v0.3.0

yizack

nuxt-mailchannels

Nuxt MailChannels

Simple MailChannels Email Send API integration for Nuxt.

Leverages @yizack/mailchannels 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: '' },
  },
})

!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,
    data: string[] | undefined,
  }>
}

Simple usage

const mailchannels = useMailChannels(event)
await mailchannels.send({
  from: {
    email: '[email protected]',
    name: 'Example 2'
  },
  to: {
    email: '[email protected]',
    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.	❌
`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.	❌
`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.	🟡
`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.	🟡
`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.	🟡
`mustaches`	Data to be used if the email is a mustache template, key-value pairs of variables to set for template rendering. Keys must be strings.	❌

!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
`success`	`boolean`	Indicates the success or failure of the email sending operation.
`data`	`string[]` or `undefined`	The fully rendered message if the `dryRun` argument is set to `true`.

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: '[email protected]',
      name: 'Example 2'
    },
    to: {
      email: '[email protected]',
      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: '[email protected]',
    to: '[email protected]',
    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: '[email protected]',
      name: 'Example 3'
    },
    to: [
      {
        email: '[email protected]',
        name: 'Example 1'
      },
      {
        email: '[email protected]',
        name: 'Example 2'
      }
    ],
    subject: 'Your subject',
    html: '<p>Your email content</p>',
    text: 'Your email content',
  })
  return { success }
})

export default defineEventHandler(async (event) => {
  const mailchannels = useMailChannels(event)
  const { success } = await mailchannels.send({
    from: '[email protected]',
    to: ['[email protected]', '[email protected]'],
    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: '[email protected]',
    to: '[email protected]',
    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: '[email protected]',
    to: '[email protected]',
    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 <[email protected]>',
    to: 'Recipient Name <[email protected]>',
    subject: 'Your subject',
    html: '<p>Your email content</p>',
    text: 'Your email content',
  })

  return { success }
})

Contribution

Local development

# Install dependencies
npm install

# 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