Simple MailChannels Email Send API integration for Nuxt.
Leverages mailchannels-sdk package, a MailChannels SDK for Node.js.
- 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
- 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.
- Add
nuxt-mailchannelsdependency to your project
npx nuxi@latest module add mailchannels- Add the module in your
nuxt.config.ts
export default defineNuxtConfig({
modules: [
'nuxt-mailchannels'
],
})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=Note
Setting environment variables will override the settings in nuxt.config.ts file.
The following helpers are auto-imported in your server/ directory.
// initialize a MailChannels instance
const mailchannels = useMailChannels(event)const useMailChannels: (event?: H3Event) => {
send: (options: MailChannelsEmailOptions, dryRun?: boolean) => Promise<EmailsSendResponse>
}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',
})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.
| 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. |
❌ |
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.
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 |
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. |
The sendAsync 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.
| Argument | Type | Description | Required |
|---|---|---|---|
options |
Options |
The email options to send | ✅ |
The options for the sendAsync method are the same as the send method.
| Property | Type | Description |
|---|---|---|
data |
EmailsSendAsyncResponse["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. |
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.
This is the best way to add names to the recipients.
export default defineEventHandler(async (event) => {
const mailchannels = useMailChannels(event)
const { success, 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 { success }
})This is the simplest way to send an email.
export default defineEventHandler(async (event) => {
const mailchannels = useMailChannels(event)
const { success, 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 { success }
})You can also send an email to multiple recipients.
export default defineEventHandler(async (event) => {
const mailchannels = useMailChannels(event)
const { success, 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 { success }
})or
export default defineEventHandler(async (event) => {
const mailchannels = useMailChannels(event)
const { success, 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 { success }
})You can use the mustaches property to render mustache templates.
export default defineEventHandler(async (event) => {
const mailchannels = useMailChannels(event)
const { success, data, error } = 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 }
})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 { success, 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 { success }
})You can use name-address pairs string format.
export default defineEventHandler(async (event) => {
const mailchannels = useMailChannels(event)
const { success, 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 { success }
})You can use the sendAsync method to queue an email message for asynchronous processing.
export default defineEventHandler(async (event) => {
const mailchannels = useMailChannels(event)
const { data, error } = await mailchannels.sendAsync({
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 }
})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