TL;DR: Learn how to customize the branding and appearance of your emails in Gadget and send them through external email services.

Despite the rise of instant communication tools like Slack, email communication is still alive and well, particularly for business and web applications. You can and should be using email as a way to communicate with your users. 

With the launch of Email/Password auth, Gadget also introduced the ability to send emails directly from your application. For Gadget developers, the <inline-code>emails<inline-code> object within your actions gives you access to the GadgetMailer (a Gadget wrapper for Nodemailer), which you can use to handle sending and integrating email functionalities into your projects.

What can you build with `emails`?

GadgetMailer makes it easy to handle emails within your applications. Whether you’re looking to use it for simple notifications to your users, or run complex marketing campaigns, it has all the features you need to get the job done.

Some examples of how you may leverage the GadgetMailer include:

• Automated Emails: From order confirmations to password resets, GadgetMailer can automate various email communications in web applications.
• Newsletters and Marketing Campaigns: It can be used to send out newsletters or marketing campaign emails, supporting rich content and attachments.
• System Alerts: GadgetMailer is ideal for sending system alerts or notifications, such as server downtime or performance issues.

Crafting Custom Email Templates

No email tool would be complete without the support for custom email templates. If you want to add your own branding to your transactional, marketing, or support emails, it’s easy to do using <inline-code>email<inline-code>. 

To build custom templates in Gadget, you can customize the HTML and CSS, and for dynamic content, templating engines like Handlebars or EJS can be integrated, allowing for personalized and unique emails for each recipient.

To create a custom email template, first define a constant (let’s call it CustomTemplate). This constant will hold an HTML5 document structured to your preference in terms of design and content. To avoid writing hundreds of lines of <inline-code><table><inline-code> <inline-code><td><inline-code> <inline-code><tr><inline-code>, we recommend looking at some existing templates that people have already created. If you’re looking for some inspiration for great email designs, you can check out resources like ReallyGoodEmails – you can explore the code for most of their featured emails, so you can see exactly how the experts build.

When it’s time to send your email using <inline-code>emails.sendMail()<inline-code>, simply pass your custom template in the <inline-code>html<inline-code> parameter. 

It should look something like this:

Remember, when using CustomTemplate in <inline-code>emails.sendMail()<inline-code>, there's no need for a <inline-code>text<inline-code> parameter as the content is already in your custom template.

If you want to add custom variable content in your email templates, you can do so by adding variables to your code, which will look something like this:

You can then insert <inline-code><%= another_variable %><inline-code> into your custom template where you want your variables to appear. 

For example, if you want to add an order number to your email, you would pass this as a parameter into renderEmailTemplate, and then use <inline-code><%=order_number %><inline-code> in your email template.

You’ll want to set up an action something like the following:

Then add the corresponding variable to your email template:

Using external email services by setting up your transporter

GadgetMailer's transporter is a versatile component that enables applications to send emails using external services. These can include popular email providers and SMTP (Simple Mail Transfer Protocol) servers, depending on the needs of your app. 

The transporter is configured to work with a variety of email services like Gmail, Outlook, Yahoo, SendGrid, Mailgun, and more. The configuration process typically requires the service provider’s SMTP settings, including host, port, and authentication details (username and password). Some services, like SendGrid or Mailgun, offer APIs that can be integrated directly with Nodemailer, offering additional features like detailed analytics and improved deliverability.

Setting up your transporter

By default, you have access to a Gadget-managed transport with a custom SMTP that runs on MailGun, so you can build and test without worrying about setting everything up until you’re ready to move to production. You can set up your production transporter in just 3 steps.

1.  Create a boot file and declare a value representing the new transport. With this value you'll run <inline-code>emails.setTransport()<inline-code>. For those familiar with Nodemailer this is exactly how <inline-code>createTransport()<inline-code> operates.

2. The parameters passed through `setTransport()` will be entirely dependent upon the type of transport you wish to use with your app. Refer to the Nodemailer documentation, or whichever transport service provider you’re using for more details on which parameters should be passed.

3. For example, if we wanted to use Mandrill (Mailchimp's transactional email service) as our email transporter we would use the following:

If you want to learn more about customizing email templates in Gadget or get feedback from other developers, join the Gadget Discord community!