Use Case: Configuring a SendGrid API Call

Overview

When you're ready to send an email using your SendGrid account, you'll do it using an API (application programming interface) call in your Unqork module. You'll use a Plug-In component to make the call, mapping the parameters in the Inputs table. When executed, your Plug-In will send a POST API call to your external SendGrid service. SendGrid will then interpret the API request body and send the email.

You might already be familiar with external services like SendGrid. So, you might already know to set up your SendGrid service before moving on with configuration. If not, you can find more information in our SendGrid Integration article.

NOTE  The SendGrid service already exists in the Unqork Training Environment. You'll only need to complete this setup if you're working in a new environment.

NOTE  Please note that SendGrid is a paid service. So, if you want to integrate SendGrid into your own environment, you'll set up your account directly through SendGrid. There are similar services that serve the same purpose as SendGrid, so use what works best for you.

Let's look at a simple example. You'll use an Email component to collect your end-user's email address. You'll also add a Button component that, when clicked, triggers your SendGrid API call. Again, you'll use a Plug-In component to manage the API call itself.

Here's how the completed use case appears in Express View:

Here's how the completed use case appears in the Module Builder:

Once you've completed your configuration, you'll look at how to test your SendGrid integration and API call.

What You'll Learn

In this article, you'll learn:

What You'll Need

To set up this use case, you’ll need:

  • 1 Columns component

  • 1 Email component

  • 1 Text Area component

  • 1 Plug-In component

  • 1 Button component

NOTE  When configuring API calls, you should always use a Proxy Module. Because this use case focuses only on configuring the API call, we won't create a Proxy Module. We'll configure the API call in our main module.

These instructions assume you have an Unqork module open and saved with a title.

Configuration

Configure the Columns Component

Your Columns component acts as a container for the components that follow.

1. Drag and drop a Columns component onto your canvas.
2. Enter colEmail in the Property ID.
3. Under Column Layout, click on the icon displaying 2 evenly spaced columns.
4. Click Save.

Configure the Email Component

This Email component serves as the recipient of your email. In a later step, you'll map this to your API call in the Plug-In component.

1. Drag and drop an Email component onto your canvas. Place the Email component inside your left-hand column.
2. Enter emailAddress in the Property ID.
3. Enter Email Address in the Label Text.
4. Click Save.

Configure the Text Area Component

This Text Area component serves as the body of your email. In the next step, you'll map this into your API call in the Plug-In component.

1. Drag and drop a Text Area component onto your canvas. Place the Text Area component inside your right-hand column.
2. Enter emailMessage in the Property ID.
3. Enter Email Message in the Label Text.
4. Click Save.

Configure the Plug-In Component

As with internal API calls, the Plug-In component ties everything together. This is where you'll map out your parameters so they're all compiled into one request body. For example, you'll take the data in your Email Address field and tell SendGrid that's the recipient. The same goes for the Email Message field, except this serves as your content. Later, you'll configure a Button component to trigger the Plug-In and send the call.

1. Drag and drop a Plug-In component onto your canvas. Place the Plug-In component beneath your columns.
2. Enter pluginSendEmail in the Property ID and Label Text.
3. Select Manual from the Trigger Type.
4. In the Inputs table, enter the following:

Property ID

Mapping

emailAddress

personalizations[0].to[0].email

emailMessage

content[0].value

‘no-reply@unqork.io'

from.email

‘Hello Subject’

subject

‘text/html’

content[0].type

NOTE  Setting any of these inputs as Required stops the API call from sending if the value is not present. Setting an input as Optional means the call sends without the parameter rather than as a blank value if that parameter is empty.

NOTE  If you've set up any global variables, you can reference those in the Inputs table.

TIP  You'll find the parameters for external API calls in the service's documentation. You'll need to include every required parameter for your call to succeed. You can find the SendGrid documentation here: https://sendgrid.com/docs/API_Reference/Web_API_v3/Mail/index.html.

5. Select External from the Service Type.
6. Select SendGrid from the External Services drop-down.
7. Select POST from the Request Type.
8. Enter mail/send in the Data Source URL.

NOTE  The Service Protocol + Host you entered when setting up SendGrid in Services Administration prepopulates here. That is consistent for any call made using SendGrid. Adding mail/send specifies that we are sending an email in this specific call.

9. Click Save.

Configure the Button Component

Finally, you'll configure a Button component as the trigger for your Plug-In. When you click this button, the Plug-In sends the API call.

1. Drag and drop a Button component onto your canvas. Place the Button component beneath your Plug-In.
2. Enter btnSendEmail in the Property ID.
3. Enter Send Email in the Label Text.
4. Select Event from the Button Action Type.
5. Enter pluginSendEmail as the Trigger on Click.

6. Click Save.
7. Save your module.

Test Your Setup

Now that you’ve completed the configuration, it’s time to test it out. You’ll do this by sending a test email to yourself. This way, you can view the original message and make sure all data passed through successfully.

NOTE  The following steps are specific to checking your configuration using an Unqork Gmail account. You can also send a test email to yourself through another email service provider.

1. Preview your module in Express View.
2. Enter your email address.
3. Enter an email message.
4. Click Send Email.
5. Open the email in your Gmail web browser.
6. From the More Options button, click Show Original.

This shows all information about your test email. If your configuration is successful, you’ll see PASS for 2 items: SPF and DKIM. If DMARC is present, you should also see PASS beside that. If you see anything other than PASS, double-check your configuration.

With this complete, you now have a working SendGrid API call. This example only begins to show what you can do when integrating with SendGrid. The customization opportunities are plentiful and can meld to fit your needs.

Lab

You can view the completed lab for this use case here: https://training.unqork.io/#/form/5fd1341b088d5d0223ce995a/edit.