Email

Documentation of Meteor's email API.

The email package allows sending email from a Meteor app. To use it, add the package to your project by running in your terminal:

meteor add email

There are two ways on how to setup the package for sending e-mail.

First is to set MAIL_URL. The server reads from the MAIL_URL environment variable to determine how to send mail. The MAIL_URL should reference an SMTP server and use the form smtp://USERNAME:PASSWORD@HOST:PORT or smtps://USERNAME:PASSWORD@HOST:PORT. The smtps:// form (the s is for “secure”) should be used if the mail server requires TLS/SSL (and does not use STARTTLS) and is most common on port 465. Connections which start unencrypted prior to being upgraded to TLS/SSL (using STARTTLS) typically use port 587 (and sometimes 25) and should use smtp://. For more information see the Nodemailer docs

Second, if you are using a one of the supported services you can setup the sending options in your app settings like this:

{
  "packages": {
    "email": {
      "service": "Mailgun",
      "user": "postmaster@meteor.com",
      "password": "superDuperPassword"
    }
  }
}

The package will take care of the rest.

If you use a supported service the package will try to match to supported service and use the stored settings instead. You can force this by switching protocol like smtp to the name of the service. Though you should only use this as a stop-gap measure and instead set the settings properly.

If neither option is set, Email.send outputs the message to standard output instead.

Package setting is only available since Email v2.2

Server
import { Email } from 'meteor/email'
(email/email.js, line 239)

Send an email. Throws an Error on failure to contact mail server or if mail server returns an error. All fields should match RFC5322 specification.

If the MAIL_URL environment variable is set, actually sends the email. Otherwise, prints the contents of the email to standard out.

Note that this package is based on nodemailer, so make sure to refer to the documentation when using the attachments or mailComposer options.

Options

from String

"From:" address (required)

to, cc, bcc, replyTo String or Array of Strings

"To:", "Cc:", "Bcc:", and "Reply-To:" addresses

inReplyTo String

Message-ID this message is replying to

references String or Array of Strings

Array (or space-separated string) of Message-IDs to refer to

messageId String

Message-ID for this message; otherwise, will be set to a random value

subject String

"Subject:" line

text, html String

Mail body (in plain text and/or HTML)

watchHtml String

Mail body in HTML specific for Apple Watch

icalEvent String

iCalendar event attachment

headers Object

Dictionary of custom headers - e.g. { "header name": "header value" }. To set an object under a header name, use JSON.stringify - e.g. { "header name": JSON.stringify({ tracking: { level: 'full' } }) }.

attachments Array of Objects

Array of attachment objects, as described in the nodemailer documentation.

mailComposer MailComposer

A MailComposer object representing the message to be sent. Overrides all other options. You can create a MailComposer object via new EmailInternals.NpmModules.mailcomposer.module.

You must provide the from option and at least one of to, cc, and bcc; all other options are optional.

Email.send only works on the server. Here is an example of how a client could use a server method call to send an email. (In an actual application, you’d need to be careful to limit the emails that a client could send, to prevent your server from being used as a relay by spammers.)

// Server: Define a method that the client can call.
Meteor.methods({
  sendEmail(to, from, subject, text) {
    // Make sure that all arguments are strings.
    check([to, from, subject, text], [String]);

    // Let other method calls from the same client start running, without
    // waiting for the email sending to complete.
    this.unblock();

    Email.send({ to, from, subject, text });
  }
});

// Client: Asynchronously send an email.
Meteor.call(
  'sendEmail',
  'Alice <alice@example.com>',
  'bob@example.com',
  'Hello from Meteor!',
  'This is a test of Email.send.'
);
Server
import { Email } from 'meteor/email'
(email/email.js, line 294)

Send an email with asyncronous method. Capture Throws an Error on failure to contact mail server or if mail server returns an error. All fields should match RFC5322 specification.

If the MAIL_URL environment variable is set, actually sends the email. Otherwise, prints the contents of the email to standard out.

Note that this package is based on nodemailer, so make sure to refer to the documentation when using the attachments or mailComposer options.

Options

from String

"From:" address (required)

to, cc, bcc, replyTo String or Array of Strings

"To:", "Cc:", "Bcc:", and "Reply-To:" addresses

inReplyTo String

Message-ID this message is replying to

references String or Array of Strings

Array (or space-separated string) of Message-IDs to refer to

messageId String

Message-ID for this message; otherwise, will be set to a random value

subject String

"Subject:" line

text, html String

Mail body (in plain text and/or HTML)

watchHtml String

Mail body in HTML specific for Apple Watch

icalEvent String

iCalendar event attachment

headers Object

Dictionary of custom headers - e.g. { "header name": "header value" }. To set an object under a header name, use JSON.stringify - e.g. { "header name": JSON.stringify({ tracking: { level: 'full' } }) }.

attachments Array of Objects

Array of attachment objects, as described in the nodemailer documentation.

mailComposer MailComposer

A MailComposer object representing the message to be sent. Overrides all other options. You can create a MailComposer object via new EmailInternals.NpmModules.mailcomposer.module.

encryptionKeys String

An array that holds the public keys used to encrypt.

shouldSign String

Enables you to allow or disallow email signing.

sendAsync only works on the server. It has the same behavior as Email.send, but returns a Promise. If you defined Email.customTransport, the callAsync method returns the return value from the customTransport method or a Promise, if this method is async.

// Server: Define a method that the client can call.
Meteor.methods({
  sendEmail(to, from, subject, text) {
    // Make sure that all arguments are strings.
    check([to, from, subject, text], [String]);

    // Let other method calls from the same client start running, without
    // waiting for the email sending to complete.
    this.unblock();

    return Email.sendAsync({ to, from, subject, text }).catch(err => {
      // 
    });
  }
});
Server
import { Email } from 'meteor/email'
(email/email.js, line 194)

Hook that runs before email is sent.

Arguments

f Function

receives the arguments to Email.send and should return true to go ahead and send the email (or at least, try subsequent hooks), or false to skip sending.

hookSend is a convenient hook if you want to: prevent sending certain emails, send emails via your own integration instead of the default one provided by Meteor, or do something else with the data. This is especially useful if you want to intercept emails sent by core packages like accounts-password or other packages where you can’t modify the email code.

The hook function will receive an object with the options for Nodemailer.

Server
import { Email } from 'meteor/email'
(email/email.js, line 205)

Overrides sending function with your own.

Arguments

f Function

function that will receive options from the send function and under packageSettings will include the package settings from Meteor.settings.packages.email for your custom transport to access.

Email.customTransport is only available since Email v2.2

There are scenarios when you have your own transport set up, be it an SDK for your mailing service or something else. This is where customTransport comes in. If you set this function all sending events will be passed to it (after hookSend is run) with an object of the options passed into send function with addition of packageSettings key which will pass in package settings set in your app settings (if any). It is up to you what you do in that function as it will override the original sending function.

Here is a simple example with Mailgun:

import { Email } from 'meteor/email'
import { Log } from 'meteor/logging'
import Mailgun from 'mailgun-js'

Email.customTransport = (data) => {
  // `options.packageSettings` are settings from `Meteor.settings.packages.email`
  // The rest of the options are from Email.send options
  const mailgun = Mailgun({ apiKey: data.packageSettings.mailgun.privateKey, domain: 'mg.mygreatapp.com' })
  
  // Since the data object that we receive already includes the correct key names for sending
  // we can just pass it to the mailgun sending message.
  mailgun.messages().send(data, (error, body) => {
    if (error) Log.error(error)
    if (body) Log.info(body)
  })
}

Note that this also overrides the development display of messages in console so you might want to differentiate between production and development for setting this function.

Edit on GitHub
// search box