Mail

Trellis' mail functionality is separated between development and staging/production since you usually want different behaviour out of them.

Development

Dealing with emails in development is never fun. The two common solutions are:

• Ignore it and hope it works fine on production
• Set up real SMTP credentials to send emails

Enter MailHog. It’s a simple tool which captures outgoing email and lets you view them from a web UI. And after that you can optionally "release" them which would actually send the email.

MailHog is automatically set up in development. You can access it at http://example.test:8025 (replacing the domain with yours that you set up for the WP site host).

Another benefit of using MailHog is that if you are using real SMTP credentials in development, you can ensure you don’t accidentally send emails to real email addresses which might exist in your database.

Trellis is using the MailHog role on Ansible Galaxy. See that README for any extra configuration options although none should be required as Trellis integrates it automatically.

Remote servers (staging/production)

Outgoing mail is done by the sSMTP role. sSMTP is a lightweight SMTP mail relay basically. In order to send external emails, you'll need to configure an SMTP server.

We always suggest using an external email service rather than your own because it's very difficult to set up a proper email server.

Some suggested services:

• Sendgrid
• Mailgun
• Amazon SES

All of these offer around 10k+ emails for free per month. Once you have SMTP credentials, configure them in group_vars/all/mail.yml.

• mail_smtp_server: hostname:port
• mail_hostname: hostname for mail delivery
• mail_user: username
• mail_password: password or "API key" (define in group_vars/all/vault.yml)

Note: Trellis sends emails through SMTP, which requires a username and password. Some email service providers refer to mail_password as an "API key", even though it is not actually used to access the email service provider's API. If you prefer to send email through your email service provider's API (instead of via SMTP), you will need to use a plugin.

Example

mail_smtp_server: smtp.example.com:587
mail_hostname: example.com
mail_user: admin@example.com
mail_password: '{{ vault_mail_password }}' # Define this in group_vars/all/vault.yml

If your SMTP settings are invalid, WordPress will return the following error message:

Could not instantiate mail function.

To fix this error, update your SMTP settings so that they're valid and then re-provision the remote server.

Revaliases

By default some system daemons, like cron send email from the hostname like this: root@mydroplet-ubuntu-s-1cpu-1gb-nyc3. To avoid blocked or spammed messages, configure sSMTP "revaliases" in trellis/roles/ssmtp/defaults/main.yml, and deploy the mail tasks, which will populate the /etc/ssmtp/revaliases file on the server.