How To: Send an Email with SendGrid in ArcGIS Velocity

1654
0
01-19-2021 01:33 PM
GregoryChristakos
Esri Contributor
2 0 1,654

ArcGIS Velocity offers the ability to send an email as part of a configurable real-time or big data analytic. This is often useful for when there are events of interest that warrant the need for an immediate notification. For example, you may need to be notified when a vehicle in your fleet has experienced engine trouble and requires assistance right away. Likewise, it could be equally imperative that you are informed about summary statistics derived by your big data analytic after it has finished processing sensor data gathered over the last month. Either way, emails allow you to act upon your data that much faster.

 

The Email output in ArcGIS Velocity allows you to send an email via an externally accessible SMTP server. You can certainly configure your email output with your own organization’s SMTP server if it is externally accessible on the internet. However, if this is not an option, or you do not have an SMTP server of your own, it is worth considering alternatives such as what is offered by Twilio’s SendGrid SMTP service.  In this blog, we will explore how you can configure your email output to use SendGrid’s SMTP server as one option for sending emails in ArcGIS Velocity.

 

What is SendGrid and how can I use it?

 

SendGrid is a cloud-based SMTP service provider. A SendGrid account with the free Email API plan can enable you to send up to 100 emails a day via SendGrid’s SMTP server. Paid subscription tiers can support even more emails. But with a few simple steps, the SendGrid SMTP Server can be configured with ArcGIS Velocity to send emails as part of your real-time and big data analytics.

 

Before getting started, it is important to note that an email will be sent for each discrete feature that an instance of the Email output receives in ArcGIS Velocity. For example, if you have configured a feed that ingests 250 events per second, and this feed is used in a real-time analytic just to send email alerts, you could accidentally emit 250 emails every second without any sort of filtering of your data as a precursor. Talk about spam! This high rate of messaging could quickly overload the capacity of your organization’s SMTP server or result in service suspension from your SMTP service provider.

 

Consider the functional design of your analytic, as well as any rate limitations from external SMTP services, before sending emails via Velocity. It may be necessary to consider a paid SMTP service subscription to guarantee a large quantity or rate of emails. However, unless necessity dictates otherwise, the best practice with email outputs is to be conservative with the number of emails generated per second, minute, hour, and so forth.

 

Configure SendGrid for ArcGIS Velocity

 

To use SendGrid for your SMTP Server needs, you will first need a SendGrid account. If you do not have a SendGrid account already, you can create one here. You can configure an account using the free Email API to get started. Consider SendGrid’s terms of service before proceeding.

 

Once you have a SendGrid account, you will then want to create a single sender identity. A sender identity essentially is what represents you as your “from” email address. This is the email address that recipients will see as the sender and is what ArcGIS Velocity will use as the from email address. You can create a single sender identity from the SendGrid dashboard upon signing into your new SendGrid account. You will need to verify your single sender identity by checking the email you had specified. If you are using an email that is part of your organizations domain, you may want to consider reviewing any DMARC policies that are in place as this could interfere with using the email address as your single identity sender. In any case, follow the instructions provided by SendGrid to configure a single sender identity.

 

Create a sender identity after you sign into SendGridCreate a sender identity after you sign into SendGrid

After you specify a single sender identity, you should be ready to send your first email with SendGrid. There are two methods to send an email. The first is to integrate using SendGrid’s Web API or SMTP Relay and the second is to build and send using marketing campaigns. For ArcGIS Velocity, you will want to choose the first method so that you can configure an SMTP [server] relay.

 

Integrate using SendGrid's SMTP relayIntegrate using SendGrid's SMTP relay

SendGrid will require that you first create an API key to authenticate with their API and send emails using their SMTP relay. The API Key acts as the password for sending emails, via the SMTP relay, in applications like ArcGIS Velocity. Once you specify a name for and generate your API Key, you will finally be provided details about the SendGrid SMTP server address, ports, username, and password (API key). Consider storing this information in a safe and secure location after it is generated. It is important to reference this information when configuring your email output(s) in Velocity. At this point, you can verify your integration.

 

Store the SMTP address, ports, username, and passwordStore the SMTP address, ports, username, and password

Configure an Email output in ArcGIS Velocity

 

Now that you have established all the necessary SendGrid components, you can access ArcGIS Velocity and begin to configure an Email output that uses the SendGrid SMTP server. Navigate to an existing analytic, or create a new one, to begin configuring an email output. When you add an email output to an analytic, you will need to first open it to configure your SMTP settings.

 

Add an email output to an analytic from the outputs folderAdd an email output to an analytic from the outputs folder

Step one when configuring an email output is to configure SMTP server options. If you refer to the SendGrid settings you stored from earlier, you will want to specify the SMTP Host property as the SendGrid SMTP Server (often smtp.sendgrid.net). By default, you can use port 465 and leave the SMTP server security property set to SSL/TLS. For the Username property, you will need to specify the username provided by SendGrid (often apikey). Lastly, for the Password property, provide your API key that was auto generated earlier.

 

Configure the SMTP Server with the SendGrid settingsConfigure the SMTP Server with the SendGrid settings

At this point, you should be ready to proceed to step 2 where you can configure your email fields. The From email address should be defined as the email you provided as your single sender identity. The remaining properties, To email addresses, Subject, and Message body can all be specified however you wish. You can either specify manual values, as I had done in the case of my Subject and Message body below, or you can reference fields and their values from your data as I had done using my “email_recipient” field for the To email address property below.

 

Configure email fields with manual entry or data valuesConfigure email fields with manual entry or data values

Once you click Complete, you should be good to go with sending emails as part of your real-time or big data analytic. It is important to remember that the free Email API that SendGrid offers has a cap of 100 emails a day. If you require more than that, it may be worth exploring an alternative subscription plan.

 

Sending emails is just one of many ways to notify others of critical events. If you are interested in seeing what other outputs are available for sending notifications, or processing data in general, feel free to visit and explore our resource on outputs in ArcGIS Velocity.

 

About the Author
ArcGIS GeoEvent Server Product Owner & member of the Real-Time GIS team.