Mail

See how to send emails in Athenna.

Introduction

Sending email doesn't have to be complicated. Athenna provides a clean, simple email API powered by the popular nodemailer package. Right now Athenna provide drivers for sending email via SMTP only, but in the future we will add support for Mailgun, Mailtrap, Amazon SES, and sendmail.

Installation

First of all you need to install @athenna/mail package and configure it. Artisan provides a very simple command to install and configure the mail library in your project. Simply run the following:

node artisan install @athenna/mail

The mail configurer will do the following operations in your project:

• Create the mail.ts configuration file.
• Add all mail providers in your .athennarc.json file.
• Add mail environment variables to .env, .env.test and .env.example.

Configuration

Athenna's email services may be configured via your application's Path.config('mail.ts') configuration file. Each mailer configured within this file may have its own unique configuration and even its own unique "transport", allowing your application to use different email services to send certain email messages.

Available mail drivers

Each mailer is powered by a "driver". The driver determines how the mail will be transported. The following mail drivers are available in every Athenna application. An entry for most of these drivers is already present in your application's Path.config('mail.ts') configuration file, so be sure to review this file to become familiar with its contents:

Driver name	Website	Built with
smtp	https://nodemailer.com/smtp/	nodemailer

note

Athenna has another driver called fake that is very helpful when running tests. The fake driver got the same signature of all other drivers, but it don't execute any operation when calling executors methods like send(), which is perfect to use within the Mock class. For more information about the FakeDriver, take a look at the mocking mail documentation section.

Sending mail

Let's see the simplest way to send a mail using Mail facade:

import { Mail } from '@athenna/mail'

await Mail.from('support@athenna.io')
  .to('user@gmail.com')
  .content('<h1>Mail content</h1>')
  .send()

You can add "to", "cc" and "bcc" recipientes by chaining their respective method together:

await Mail.from('support@athenna.io')
  .to('user@gmail.com')
  .cc('txsoura@athenna.io')
  .bcc('support@athenna.io')
  .content('<h1>Mail content</h1>')
  .send()

Sending mail via a specific mailer

By default, Athenna will send email using the mailer configured as the default mailer in your application's mail configuration file. However, you may use the mailer() method to send a message using a specific mailer configuration:

await Mail.mailer('my-mailer') 👈
  .from('support@athenna.io')
  .to('lenon@athenna.io')
  .content('Mail content')
  .send()

Sending Text and Markdown as content

To send text as the content of the mail, you can set the type property in second argument:

await Mail.mailer('my-mailer')
  .from('support@athenna.io')
  .to('lenon@athenna.io')
  .content('Mail content', { type: 'text' }) 👈
  .send()

And for markdowns you can use the markdown type:

await Mail.mailer('my-mailer')
  .from('support@athenna.io')
  .to('lenon@athenna.io')
  .content('# Mail content', { type: 'markdown' }) 👈
  .send()

Using view template as content

The mail component is integrated with the view component to be able to render and send a view as the body of the email. To do so you can use the view() method of the Mail facade:

const userEmail = 'lenon@athenna.io'

await Mail.from('support@athenna.io')
  .to(userEmail)
  .cc('mailer1@athenna.io, mailer2@athenna.io')
  .bcc('mailer3@athenna.io, mailer4@athenna.io')
  .content('This is the mail body')
  .view('mail/welcome', { email: userEmail }) 👈
  .send()

Any data that you provide using the Mail facade will be available to you in your view:

Path.views('mail/welcome.edge')

<!-- Provided by you when using Mail facade methods -->
<h1>{{ to }}</h1>
<h1>{{ cc }}</h1>
<h1>{{ bcc }}</h1>
<h1>{{ from }}</h1>
<h1>{{ content }}</h1>

<!-- Provided by you second argument -->
<h1>{{ email }}</h1>

tip

You can overwrite data set by Mail facade by defining it in the second argument object:

const userEmail = 'lenon@athenna.io'

await Mail.from('support@athenna.io')
  .to(userEmail)
  .cc('mailer1@athenna.io, mailer2@athenna.io')
  .bcc('mailer3@athenna.io, mailer4@athenna.io')
  .content('This is the mail body')
  .view('mail/welcome', { 
    email: userEmail, 
    to: 'txsoura@athenna.io' 👈
  })
  .send()

Previewing mail templates in the browser

When designing a mailable's template, it is convenient to quickly preview the rendered mailable in your browser like a typical Edge template. For this reason, Athenna allows you to return any mailable directly from a route using the Route.view() method, allowing you to quickly preview its design without needing to send it to an actual email address:

Path.routes('http.ts')

Route.view('/mailable', 'mail/welcome', { email: 'lenon@athenna.io' })