Courier.com

How to Send Email with Ruby

Introduction

You’ll learn how to set up your email service, design your email template, and test and preview your email before publishing it to production. You’ll also find sample code you can use to quickly start sending in your Ruby program.

Table of contents

1. Set up your transactional email service

2. Set up the email channel in Courier

3. Design and preview your email

4. Send emails from your Ruby app

Requirements to send email with Ruby

  • A registered domain, e.g. myapplication.com.
  • An email service like SendGrid, Mailgun, or an SMTP server.
  • A Courier account — it’s free to sign up and includes 10,000 notifications per month.

If you don’t already have an email service or a Courier account, we’ll show you how to set them up. While most email service providers have their own API that you can integrate directly into your app, using Courier allows you to design and manage your templates outside of your source code. Courier also provides you with critical functionality like automatically retrying failed sends and tracking deliverability and user engagement — without having to build it yourself.

In this tutorial, we’ll use Courier’s full-featured visual editor to design and preview the email, and we’ll use Courier’s integration with the email service to actually deliver your notification.

Ready? Let’s dive in.

1. Set up your transactional email service

If you already have an email service set up for your domain, you can skip ahead to the next step and set up your email channel in Courier, including integrating with your ESP.

Select your email service provider

You can see the full list of supported providers in Courier here.

Next, we’ll show you how to sign up for an ESP and configure your account. We’ll use SendGrid as an example, since they’re a well-known provider with a free plan. You can send up to 100 emails per day with SendGrid’s free plan, which should be enough to get you started.

Create your SendGrid account

Authenticate your domain in SendGrid

We highly recommend authenticating your domain, which will improve your sending reputation and email deliverability. Domain authentication also removes the “via sendgrid.net” message that some inbox providers append to your emails.

To authenticate your domain as a sender, go to Settings > Sender Authentication and then click on Get Started. You’ll need access to your DNS host to complete the authentication. Your DNS host is where you registered your domain, e.g. Rackspace, Cloudflare, Google Cloud.

On the next screen, select your DNS host and choose whether you want to brand your tracking links with your domain instead of sendgrid.net. Implementing link labeling helps ensure your emails will make it through spam filters.

Enter the domain name that you want to send emails from. Your domain needs to match the domain of the From address on the emails you’re sending out.

You’ll see the `CNAME` records that SendGrid wants to add to your DNS host. To complete your domain authentication, install these records with your DNS host and then click Verify.

Here’s an example of adding the records to Google Cloud Domains:

Create your SendGrid API key

Name your API key — we recommend picking something that’ll be easy to identify later like “Courier App” — and choose Restricted Access. Courier needs full access to Mail Send and read access for Email Activity in order to send and track emails using SendGrid.

Now you should see your API key. Keep this window open because you’ll need it in a moment.

2. Set up the email channel in Courier

Sign up for Courier

Integrate your email service provider

In this case, select SendGrid and then input your API Key from the previous step along with your From Address. Make sure the From Address matches the domain you authenticated in SendGrid. Then click Install. That’s it — SendGrid is now fully integrated with Courier!

3. Design and preview your email in Courier

Use the visual editor to design your email

You can also reference external data in your email using variables. Just use braces {} to add the variables to your email. In this case, we’ll include the person’s username and the date that they activated their account. We recommend creating a test event — which we explain below — to ensure you’re referencing the correct variable names before you publish your email.

Customize your brand

From here, you can upload your logo, set your brand color, and add text and social links to your footer. If you want to send whitelabeled emails, you can do that by creating multiple Brands.

Create a test event

You should now see the JSON data for your test event. You can add variables to either the `data` or `profile` object. In order for variables to work, you must include this data when you integrate the email into your Ruby app, which we explain in the next step. For our account activation email, we’ll add `username` and `date` to the `data` object and set values for them.

Preview your email

Publish your email

4. Send emails from your Ruby app

Install the Courier Ruby gem

gem 'trycourier'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install trycourier

Set your environment variables

Map your email notification to an event

Setting an Event ID will enable you to reference the string when making the API request instead of the Notification ID that Courier generates for you. Now, if you ever want to map this event to a different notification, you can do so inside Courier without shipping any new code. All you’d need to do is map the Event ID to the new notification using the same process we follow below.

To create an Event ID for your email, click Events under your Notifications Settings. Type in the name for your new event — in this case, `New Account` and click Create.

Copy-paste the code snippet from Courier

Next copy-paste the code into your Ruby app and, optionally, you can send another test email using the values from your test event. Your `event` value will be the Event ID you set up earlier — for this example, our Event ID is `New Account.` If you didn’t set up an Event ID, you can set the value to your Notification ID instead.

A `recipient` is a unique identifier for an individual user that doesn’t change, such as their unique username in your database. Courier uses `recipient` to prevent you from sending duplicate notifications if, for example, a user changes their email or another identifying value. You can also use it later to check the status of all the notifications you’ve sent to a particular user.

The `profile` object should include any key-value pairs required by the integration — in this case, SendGrid requires an `email` key and value. The `data object` is where we define our variables. If you remember, that’s `username` and `date` for our account activation email.

The body of your request to Courier’s Send API should look like this:

require "trycourier"   begin
client = Courier::Client.new
res = client.send({
"event" => "New Account",
"recipient" => "User123",

"profile" => {
"email": "user123@example.com",
},
"data" => {
"username" => "User123",
"date" => "November 20, 2020"
}
})
puts res.code # the HTTP response code
puts res.message_id # if 200, this will be the Courier message ID for this notification
rescue Courier::ResponseError => re
puts re.message
rescue Courier::InputError => ie
puts ie.message end

Start sending emails from your Ruby app

PS. We didn’t have time to cover everything in this tutorial, but you can also use Courier to manage your send logic, track delivery and engagement, and integrate additional channels like SMS, push, and messaging apps.

Author: Aydrian Howard

Originally published at https://www.courier.com.

Courier is the fastest way for developers to build notifications for their apps. With one API and easy-to-use UI trigger multi-channel notifications at scale.