How-to: Integrate Gmail Actions with your App

Picture of Russell Smith
Russell Smith, Thursday April 24, 2014

We all use Gmail at Rainforest. Tons of people use it, so we've decided to make it easier for you to get to your detailed results in our app. You may have noticed recent emails from us have extra buttons on them - these are 'Gmail actions'.

Rainforest Gmail Actions

Now Rainforest result emails come with a super handy link to view the results. You don't have to do anything to take advantage of this if you're already using Gmail (they've been out since Google I/O 2013 but seem relatively unused until recently).

How-to

The docs from Google are complete, but aren't the quickest. I'll run you through the fastest way to use actions: adding a 'ViewAction' (aka, link). It should take you about 5 minutes to get testing!

1. Add the code to your email template

We use the following script in our emails;

javascript <script type='application/ld+json'> { "@context": "http://schema.org", "@type": "EmailMessage", "name": "Rainforest Run started at <%= @run.created_at.in_time_zone(ADMIN_TZ).strftime('%l:%M') %> results", "action": { "@type": "ViewAction", "name": "View results", "url": "<%=link_to(@run)%>" } } </script>

As you can see it's pretty simple. The customizable parts are name and action name and url - just replace with the desired text and links!

2. Test

Until you're white-listed (more on this later), you can only test if the to and from fields match. Just send to yourself!

3. Setup and check your DKIM and SPF is working

Background: DKIM and SPF are ways of checking that a SMTP server is allowed to send email for domain. SPF is older but simple, DKIM uses a private key to sign the messages and receiving servers validate the signature against a public key retrieved from DNS.

For whitelisting to work, valid DKIM and SPF are required. To check your status, find the email you sent to yourself earlier in Gmail and click on the down arrow next to reply, click 'Show original'. You should then see the raw email, complete with headers.

You're looking for two lines - spf=pass ... and dkim=pass ...;

Received-SPF: pass (google.com: domain of pm_bounces@pm.mtasv.net designates 50.31.156.120 as permitted sender) client-ip=50.31.156.120; Authentication-Results: mx.google.com; spf=pass (google.com: domain of pm_bounces@pm.mtasv.net designates 50.31.156.120 as permitted sender) smtp.mail=pm_bounces@pm.mtasv.net; dkim=pass header.i=accounts@rainforestqa.com

If you see that, you're good to go. If not - follow the instructions for setting up SPF and DKIM - note, both will require DNS changes, but are otherwise pretty simple.

4. Request whitelisting

Request whitelisting using this form. Details here. We had a quick back and fourth with some lovely people at Google about this and future use cases, it was then approved. It took ~4-5 days to actually get pushed in to production at their end though.

Thats it! Simple! What will you be adding to your emails? Let us know on twitter.