Mail

node ace add @adonisjs/mail

node ace add @adonisjs/mail --transports=resend --transports=smtp

import env from '#start/env'
import { defineConfig, transports } from '@adonisjs/mail'

const mailConfig = defineConfig({
  /**
   * The mailer to use when none is specified
   */
  default: 'smtp',

  /**
   * Global "from" address used when not set on individual emails
   */
  from: {
    address: 'hello@example.com',
    name: 'My App',
  },

  /**
   * Global "reply-to" address used when not set on individual emails
   */
  replyTo: {
    address: 'support@example.com',
    name: 'My App Support',
  },

  /**
   * Configure one or more mailers. Each mailer uses a transport
   * and can have its own settings.
   */
  mailers: {
    smtp: transports.smtp({
      host: env.get('SMTP_HOST'),
      port: env.get('SMTP_PORT'),
    }),

    resend: transports.resend({
      key: env.get('RESEND_API_KEY'),
      baseUrl: 'https://api.resend.com',
    }),
  },
})

export default mailConfig

import type { HttpContext } from '@adonisjs/core/http'
import mail from '@adonisjs/mail/services/main'
import User from '#models/user'

export default class UsersController {
  async store({ request }: HttpContext) {
    const user = await User.create(request.all())

    /**
     * Send a welcome email after creating the user.
     * The callback configures the message properties.
     */
    await mail.send((message) => {
      message
        .to(user.email)
        .from('welcome@example.com')
        .subject('Welcome to our app!')
        .htmlView('emails/welcome', { user })
    })

    return user
  }
}

await mail.send((message) => {
  message
    .subject('Your order has shipped')
    .from('orders@example.com')
})

await mail.send((message) => {
  message.from({
    address: 'orders@example.com',
    name: 'Acme Store'
  })
})

await mail.send((message) => {
  message
    .to(user.email)
    .cc(user.manager.email)
    .bcc('audit@example.com')
})

await mail.send((message) => {
  message
    .to({
      address: user.email,
      name: user.fullName,
    })
    .cc([
      { address: 'team-lead@example.com', name: 'Team Lead' },
      { address: 'pm@example.com', name: 'Project Manager' }
    ])
})

await mail.send((message) => {
  message
    .from('noreply@example.com')
    .replyTo('support@example.com')
})

await mail.send((message) => {
  /**
   * Inline content works for simple emails
   */
  message.html(`
    <h1>Reset your password</h1>
    <p>Click <a href="${resetUrl}">here</a> to reset your password.</p>
  `)

  message.text(`
    Reset your password
    Visit ${resetUrl} to reset your password.
  `)
})

node ace make:view emails/password_reset_html
node ace make:view emails/password_reset_text

await mail.send((message) => {
  /**
   * Render Edge templates, passing data as the second argument
   */
  message.htmlView('emails/password_reset_html', { user, resetUrl })
  message.textView('emails/password_reset_text', { user, resetUrl })
})

npm i mjml

@mjml()
  <mjml>
    <mj-body>
      <mj-section>
        <mj-column>
          <mj-text font-size="20px" color="#333">
            Welcome, {{ user.name }}!
          </mj-text>
          <mj-button href="{{ verifyUrl }}">
            Verify Email
          </mj-button>
        </mj-column>
      </mj-section>
    </mj-body>
  </mjml>
@end

@mjml({
  keepComments: false,
  fonts: {
    Lato: 'https://fonts.googleapis.com/css?family=Lato:400,500,700'
  }
})
  {{-- MJML content --}}
@end

import mail from '@adonisjs/mail/services/main'

export default class UsersController {
  async store({ request }: HttpContext) {
    const user = await User.create(request.all())

    /**
     * Queue the email instead of sending immediately.
     * The request completes without waiting for delivery.
     */
    await mail.sendLater((message) => {
      message
        .to(user.email)
        .from('welcome@example.com')
        .subject('Welcome!')
        .htmlView('emails/welcome', { user })
    })

    return user
  }
}

npm i bullmq

import { Queue } from 'bullmq'
import mail from '@adonisjs/mail/services/main'

const emailsQueue = new Queue('emails')

mail.setMessenger((mailer) => {
  return {
    async queue(mailMessage, config) {
      /**
       * Store the compiled message, config, and mailer name.
       * A worker process will pick this up and send it.
       */
      await emailsQueue.add('send_email', {
        mailMessage,
        config,
        mailerName: mailer.name,
      })
    }
  }
})

import { Worker } from 'bullmq'
import mail from '@adonisjs/mail/services/main'

new Worker('emails', async (job) => {
  if (job.name === 'send_email') {
    const { mailMessage, config, mailerName } = job.data

    /**
     * Send the pre-compiled message using the specified mailer
     */
    await mail.use(mailerName).sendCompiled(mailMessage, config)
  }
})

import mail from '@adonisjs/mail/services/main'

/**
 * Send transactional emails through the default mailer
 */
await mail.send((message) => {
  message.subject('Order confirmed')
})

/**
 * Send marketing emails through Mailgun
 */
await mail.use('mailgun').send((message) => {
  message.subject('Weekly newsletter')
})

/**
 * Queue emails through a specific mailer
 */
await mail.use('resend').sendLater((message) => {
  message.subject('Your report is ready')
})

import mail from '@adonisjs/mail/services/main'

/**
 * Close the mailgun connection and remove from cache
 */
await mail.close('mailgun')

/**
 * Next call creates a fresh instance
 */
mail.use('mailgun')

import app from '@adonisjs/core/services/app'

await mail.send((message) => {
  message.attach(app.makePath('storage/invoices/inv-001.pdf'))
})

await mail.send((message) => {
  message.attach(app.makePath('storage/invoices/inv-001.pdf'), {
    filename: 'invoice-october-2024.pdf',
    contentType: 'application/pdf',
  })
})

import fs from 'node:fs'

await mail.send((message) => {
  /**
   * Attach from a readable stream
   */
  message.attachData(fs.createReadStream('./report.pdf'), {
    filename: 'report.pdf'
  })

  /**
   * Attach from a buffer
   */
  message.attachData(Buffer.from('Hello world'), {
    filename: 'greeting.txt',
    encoding: 'utf-8',
  })
})

<img src="{{ embedImage(app.makePath('assets/logo.png')) }}" alt="Logo" />

<img src="{{ embedImageData(chartBuffer, { filename: 'chart.png' }) }}" />

import { DateTime } from 'luxon'

await mail.send((message) => {
  message.icalEvent((calendar) => {
    calendar.createEvent({
      summary: 'Project kickoff meeting',
      start: DateTime.now().plus({ days: 1 }).set({ hour: 10 }),
      end: DateTime.now().plus({ days: 1 }).set({ hour: 11 }),
      location: 'Conference Room A',
    })
  }, {
    method: 'REQUEST',
    filename: 'meeting.ics',
  })
})

import app from '@adonisjs/core/services/app'

await mail.send((message) => {
  /**
   * From a local file
   */
  message.icalEventFromFile(
    app.resourcesPath('invites/standup.ics'),
    { method: 'REQUEST', filename: 'standup.ics' }
  )

  /**
   * From a URL
   */
  message.icalEventFromUrl(
    'https://example.com/calendar/event-123.ics',
    { method: 'REQUEST', filename: 'event.ics' }
  )
})

await mail.send((message) => {
  message.header('X-Entity-Ref', 'order-12345')
  message.header('X-Priority', '1')
})

await mail.send((message) => {
  message.preparedHeader(
    'X-Custom-Data',
    'value with special chars or very long content'
  )
})

await mail.send((message) => {
  message.listUnsubscribe({
    url: 'https://example.com/unsubscribe?token=abc',
    comment: 'Unsubscribe from this list'
  })

  message.listHelp('support@example.com?subject=help')

  /**
   * For other List-* headers
   */
  message.addListHeader('post', 'https://example.com/list/post')
})

node ace make:mail verify_email

import User from '#models/user'
import router from '@adonisjs/core/services/router'
import { BaseMail } from '@adonisjs/mail'

export default class VerifyEmailNotification extends BaseMail {
  /**
   * Set class properties for common message options
   */
  from = 'noreply@example.com'
  subject = 'Please verify your email address'

  constructor(private user: User) {
    super()
  }

  /**
   * Configure the message in the prepare method.
   * Called automatically before sending.
   */
  prepare() {
    const verifyUrl = router.makeUrl('email.verify', {
      token: this.user.verificationToken
    })

    this.message
      .to(this.user.email)
      .htmlView('emails/verify_email', {
        user: this.user,
        verifyUrl,
      })
  }
}

import mail from '@adonisjs/mail/services/main'
import VerifyEmailNotification from '#mails/verify_email'

export default class AuthController {
  async register({ request }: HttpContext) {
    const user = await User.create(request.all())

    await mail.sendLater(new VerifyEmailNotification(user))

    return { message: 'Check your email to verify your account' }
  }
}

import { test } from '@japa/runner'
import mail from '@adonisjs/mail/services/main'
import VerifyEmailNotification from '#mails/verify_email'

test.group('Users | register', (group) => {
  group.each.setup(() => {
    /**
     * Restore the real mailer after each test
     */
    return () => mail.restore()
  })

  test('sends verification email on registration', async ({ client }) => {
    const { mails } = mail.fake()

    await client
      .post('/register')
      .form({ email: 'user@example.com', password: 'secret123' })

    /**
     * Assert the email was sent
     */
    mails.assertSent(VerifyEmailNotification, ({ message }) => {
      return message
        .hasTo('user@example.com')
        .hasSubject('Please verify your email address')
    })
  })

  test('does not send password reset when user not found', async ({ client }) => {
    const { mails } = mail.fake()

    await client
      .post('/forgot-password')
      .form({ email: 'unknown@example.com' })

    mails.assertNotSent(PasswordResetNotification)
  })
})

import { test } from '@japa/runner'
import { UserFactory } from '#database/factories/user_factory'
import VerifyEmailNotification from '#mails/verify_email'

test.group('VerifyEmailNotification', () => {
  test('builds correct message', async () => {
    const user = await UserFactory.create()
    const email = new VerifyEmailNotification(user)

    /**
     * Build the message and render templates
     */
    await email.buildWithContents()

    /**
     * Assert message properties
     */
    email.message.assertTo(user.email)
    email.message.assertFrom('noreply@example.com')
    email.message.assertSubject('Please verify your email address')

    /**
     * Assert rendered content
     */
    email.message.assertHtmlIncludes(`Hello ${user.name}`)
    email.message.assertHtmlIncludes('/verify/')
  })
})

const { mails } = mail.fake()

/**
 * Get all sent emails
 */
const sentEmails = mails.sent()

/**
 * Get all queued emails
 */
const queuedEmails = mails.queued()

/**
 * Find a specific email
 */
const verifyEmail = sentEmails.find((email) => {
  return email instanceof VerifyEmailNotification
})

if (verifyEmail) {
  verifyEmail.message.assertHtmlIncludes('Verify your email')
}

import nodemailer from 'nodemailer'
import postmarkTransport from 'nodemailer-postmark-transport'
import { MailResponse } from '@adonisjs/mail'
import type { NodeMailerMessage, MailTransportContract } from '@adonisjs/mail/types'

export type PostmarkConfig = {
  auth: {
    apiKey: string
  }
}

export class PostmarkTransport implements MailTransportContract {
  #config: PostmarkConfig

  constructor(config: PostmarkConfig) {
    this.#config = config
  }

  async send(
    message: NodeMailerMessage,
    config?: PostmarkConfig
  ): Promise<MailResponse> {
    /**
     * Create nodemailer transport with merged config
     */
    const transporter = nodemailer.createTransport(
      postmarkTransport({ ...this.#config, ...config })
    )

    const response = await transporter.sendMail(message)

    /**
     * Return normalized response
     */
    return new MailResponse(response.messageId, response.envelope, response)
  }
}

import type { MailManagerTransportFactory } from '@adonisjs/mail/types'

export function postmarkTransport(
  config: PostmarkConfig
): MailManagerTransportFactory {
  return () => new PostmarkTransport(config)
}

import env from '#start/env'
import { defineConfig } from '@adonisjs/mail'
import { postmarkTransport } from '#app/mail/transports/postmark'

const mailConfig = defineConfig({
  mailers: {
    postmark: postmarkTransport({
      auth: {
        apiKey: env.get('POSTMARK_API_KEY'),
      },
    }),
  },
})

import { Message } from '@adonisjs/mail'

Message.templateEngine = {
  async render(templatePath, data) {
    /**
     * Use your preferred template engine
     */
    return myTemplateEngine.render(templatePath, data)
  }
}