Email

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

Email.send

Server only

Summary:

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.

Arguments:

Source code

Name	Type	Description	Required
options	Object		Yes

Options:

Name	Type	Description	Required
from	String	"From:" address (required)	No
to, cc, bcc, replyTo	String	"To:", "Cc:", "Bcc:", and "Reply-To:" addresses	No
inReplyTo	String	Message-ID this message is replying to	No
references	String	Array (or space-separated string) of Message-IDs to refer to	No
messageId	String	Message-ID for this message; otherwise, will be set to a random value	No
subject	String	"Subject:" line	No
text, html	String	Mail body (in plain text and/or HTML)	No
watchHtml	String	Mail body in HTML specific for Apple Watch	No
icalEvent	String	iCalendar event attachment	No
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' } }) }.	No
attachments	Array.<Object>	Array of attachment objects, as described in the nodemailer documentation.	No
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.	No
encryptionKeys	String	An array that holds the public keys used to encrypt.	No
shouldSign	String	Enables you to allow or disallow email signing.	No

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.js

import { Meteor } from "meteor/meteor";
import { Email } from "meteor/email";
import { check } from "meteor/check";
// 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]);

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

client.js

import { Meteor } from "meteor/meteor";
// Client: Asynchronously send an email.
Meteor.callAsync("sendEmail", {
  to: "Alice <alice@example.com>",
  from: "bob@example.com",
  subject: "Hello from Meteor!",
  text: "This is a test of Email.send.",
});

Email.sendAsync

Server only

Summary:

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.

Arguments:

Source code

Name	Type	Description	Required
options	Object		Yes

Options:

Name	Type	Description	Required
from	String	"From:" address (required)	No
to, cc, bcc, replyTo	String	"To:", "Cc:", "Bcc:", and "Reply-To:" addresses	No
inReplyTo	String	Message-ID this message is replying to	No
references	String	Array (or space-separated string) of Message-IDs to refer to	No
messageId	String	Message-ID for this message; otherwise, will be set to a random value	No
subject	String	"Subject:" line	No
text, html	String	Mail body (in plain text and/or HTML)	No
watchHtml	String	Mail body in HTML specific for Apple Watch	No
icalEvent	String	iCalendar event attachment	No
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' } }) }.	No
attachments	Array.<Object>	Array of attachment objects, as described in the nodemailer documentation.	No
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.	No

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]);

    return Email.sendAsync({ to, from, subject, text }).catch((err) => {
      // do something with the error
    });
  },
});

Email.hookSend

Server only

Summary:

Hook that runs before email is sent.

Arguments:

Source code

Name	Type	Description	Required
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.	Yes

import { Email } from 'meteor/email'

Email.hookSend(({to}) => {
  if (to === 'ceo@company.com') {
    console.log(`Let's not send email to the CEO`);
    return false;
  }
  return true;
})

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.

Email.customTransport

Server only

Summary:

Overrides sending function with your own.

Arguments:

Source code

Name	Type	Description	Required
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.	Yes

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.