This is the first in a series of articles on using the Gmail API from FileMaker. We’ll provide free example files for each post and these examples will all use the native Insert From URL script step so there won’t be any plug-ins required.

In this article, we’re going to look at sending HTML emails. In future articles, I’ll examine sending large emails (35MB) with multiple attachments, resumable uploading, and managing threads. This approach provides a first-rate email experience that is not available using the native Send Mail script step. And, since the Insert From URL script step is supported natively across the whole FileMaker platform, the techniques shown here work on the Server, Go, FileMaker Cloud and WebDirect. This technique requires FileMaker 16 or higher since we’ll be using the advanced cURL options introduced in FileMaker 16.

Here’s an introduction. Step-by-step instructions and an unlocked example file follow:

Background and Choosing the Gmail API

I recently had the opportunity to build a comprehensive Gmail integration into a client’s system. The main reason the client wanted to go the Gmail route was to have seamless integration with their native Gmail experience; at first they weren’t that interested in threads or large attachments, but those features soon became important once they started emailing from within FileMaker.

Before we started, the client and I discussed which route we wanted to take, like using a plug-in or rolling our own. Fortunately, right about this time, dbservices published a great blog post and example file on integrating with the Gmail API. This article provided great techniques for authenticating to Google as well as creating an inbox in FileMaker that would import Gmails with their attachments. Basically, they had already done a lot of the work we needed. I implemented their authentication and inbox routine and then added the techniques I’m going to share here.

Example File

Please download the example file FM2Gmail for a working demo. This first version just covers the sending of HTML emails and we’ll be providing later versions of this file in future articles.

Integrating FileMaker and Gmail - Example File

FM2Gmail Example File

 

Getting Started / Authentication

Before we can send any emails, we’ll need to authenticate our app to Google. Our example file has adapted the authentication routine provided by dbservices where you’ll find more details on setting up a Google project for the OAuth values. Specify Web Application for your project so the redirect URI value is available. Once you’ve got your Client ID and Client Secret you can enter them into the fields on the OAuth settings page.

Integrating FileMaker with Gmail - Settings

Settings Popover

 

Authenticating Google Account within FileMaker

Authentication Set-Up

With your Client ID and Client Secret entered, you can click the “authenticate to gmail” link on the left. This opens a web viewer in a card window where you can log-into your Google account and authorize access to your Gmail data.

Authorize FileMaker to access Gmail

Authorize your app to access Gmail data

When you’ve successfully authenticated and authorized you’ll see your email address take the place of the “authenticate to gmail” link.

Important!

At this point, the example file has an authorization Refresh Token which we’ll use to automatically authenticate when the file opens in the future. So take some care with the file once it’s authorized as it will have access to your Gmail when opened. You can de-authorize the app access at any time by visiting “My Account” from your Google settings and then finding Apps with account access section. From there you can de-authorize the app.

Integrating FileMaker and Gmail Authorization

Remove app access from Google

Sending an HTML Email from FileMaker

Now that we’re authorized, the new email button appears, and we can compose and send something. I was going to use a card window for the compose layout, but I wanted to expose the formatting bar so went with a Floating window instead. (Exposing the formatting bar is an old FileMaker Hacks trick). Showing the formatting bar lets you easily add some styles to our text; those text styles will get transformed into styled HTML.]

Compose HTML email in FIleMaker

Composing an email with styled text

I also added a simple emoji picker for fun. These are just button bars that are passing the emoji characters into the text. Since we’re just using the unicode characters, the emojis are a little spartan on Windows but work fine for a simple demo.

Emoji Picker for FileMaker

An Emoji Picker

We can then send our Email and when we look at it in the recipient’s inbox we see that the styling has come across as an HTML email.

Inbox

AppleMail

Under The Hood

To send an email via the Gmail API we first need to create the email form following the RFC822 standard. This multipart form may be familiar to many of you already and looks like the following:

 

In our sample file, the Script “Create RFC822 Form” is used to build the above. The RFC822 standard does call out using CRLF (carriage return + line feed) for the line breaks, but I had better luck just using the line feed or Char(10) in FileMaker terms. This allowed for leaving header values like CC blank and a more straightforward template.

Notice that there are two parts to this form that contains the message. The first is the text/plain section where we pass the plain text from our field. Since this is plain text, all of the formattings we applied is gone. Below, in the text/html section, we pass in the HTML representation of our message with any appropriate styling. Even though most modern email clients and browsers support reading HTML messages, it’s considered best practice to pass the plaintext message as well.

To generate the HTML in our sample file we’re just using FileMaker’s GetAsCSS() function. This actually works very well for a basic example and translates all of the formatting options except for any fonts applied. If you need a more robust HTML editor then something like FMEasyHTML from Tim Dietrich or Editor by Geist Interactive are worth checking out.

The Script “Send Email – Simple”

Once we have our form built, then we can POST it to the Gmail API using the Insert From URL script step. The example file does this in the script “Send Email – Simple”. Here’s what that script does:

Our target URL is:

 

This is the endpoint for our simple upload example and it supports an email up to 5MB. In the next article, we’ll be looking at a different URL that allows for up to 35MB with multiple attachments.

Now we just need to set a few cURL settings for our headers. (The exaple file writes the access token to a global variable when authentication is complete).

And then specify our request body which is the rfc822 form we created above.

And also capture the result headers to a variable in case we need to examine them for errors.

That’s it!. This is all done in the script Send Email – Simple so you can step through there to see how it’s put together.

If there’s an error in the POST, an error code and message will be returned in the response body and headers. Otherwise, you’ll get a simple JSON response like this indicating the email has been sent.

Our script grabs the id and the thread id and writes those to the email record in FileMaker as we’ll be looking at using those in a future example.

Conclusions

Even though there is some extra effort involved in accessing the Gmail API, like authentication, understanding the syntax, and cURL requirements, the benefits provided by the API are well worth it. Having techniques that work across all aspects of the FileMaker platform to extend your app’s email functionality can provide massive value to your customers.

Additionally, as FileMaker developers, our understanding this kind of integration is going to be more and more expected as FileMaker continues to focus on integrating with other platforms. From my experience, every integration I do with a new API makes the next one easier. Even if you don’t have an immediate need for Gmail integration, running through this process and understanding how this API works with something familiar, like email, can only make you a better FileMaker developer.

Here’s the next article in this series:

Integrating FileMaker and Gmail Part 2 – Sending Large Attachments

Tagged with →  

7 Responses to Integrating FileMaker and Gmail Part 1 – Sending HTML Emails

  1. Daniel Farnan says:

    This is a nice implementation, Jason – thank you for providing it!

    I would note, however, that the Gmail API documentation (https://developers.google.com/gmail/api/guides/sending) specifies using the RFC2822 standard and not the RFC822 mentioned in your article. For most purposes there is a negligible difference between the two, but it’s worth paying attention to this sort of thing in case those rare errors show up.

    I also note that RFC2822 was superseded in 2008 by RFC5322 (https://en.wikipedia.org/wiki/Email#Internet_Message_Format), so the Gmail API may be upgraded at some point to make use of the new standard.

    • Jason Young says:

      Hey Daniel,
      Thank you very much for pointing that out. I was going by the Content-Type headers in the docs on uploading media that all still reference message/rfc822. I’ll make some edits to the original post and to my upcoming ones to make this more clear.
      Thank Again!!

  2. Jim says:

    Thank you for the article. It is something I’ve considering doing but was not sure where to start or how much was involved.

  3. Will Bullard says:

    As always a great SeedCode video that enriches the FileMaker community with new options to explore. Thanks for sharing these techniques.

  4. Kudos ! Great article as always :)

  5. Joe Byrne says:

    Excellent. When is Part II coming? Can’t wait!

Leave a Reply

Your email address will not be published. Required fields are marked *

Share →
Shop The SaleYear End Sale: up to 25% off all add-ons
DOWNLOAD
DayBack Calendar
DayBack's 30-day trial is unlocked so you can customize it and integrate it with your files.
Download DayBack and we'll send you a couple short emails with tips on how to modify it and use some of the coolest features.
Thank you! Please download: DayBack Calendar
Need More?
SeedCode tips & example files in your inbox
Need More?
SeedCode tips & example files in your inbox
Want More?
Be the first to see articles and tips like these
DOWNLOAD
TimeZync
Download TimeZync and we'll send you a couple short emails with tips syncing your FileMaker Go files.
Thank you! Please download: TimeZync
Want More?
Be the first to see articles and tips like these