Last modified September 15, 2016 by Shelly Wolfe

SendGrid

Sendgrid logoSendGrid is a transactional email delivery and management service. The SendGrid Adaptor enables you to trigger template-based emails and manage email subscription lists from Swrve based on user actions within the app. It also processes email delivery and engagement statistics sent from SendGrid to Swrve.

Supported Actions

The SendGrid Adaptor supports the following actions:

Outbound Actions

  • Send a template-based email
  • Subscribe user to an email list
  • Unsubscribe user from an email list

Inbound Actions

  • Process email delivery and email engagement events from SendGrid

Use Cases

Transactional Emails

Transactional emails are sent in response to a user’s real-time action in the app. For example:

  • Send a welcome email after the customer completes the sign up process.
  • Send a purchase receipt email after the customer completes a purchase.

Using the SendGrid adaptor, Swrve triggers a transactional email upon receipt of a selected user action that is configured as a mobile event. There are two main steps involved in triggering transactional emails via the SendGrid adaptor:

  1. Create a custom event in the Swrve SDK for the user action you want to use to trigger the email send process; for example, registration_complete.
  2. Create an Amplify rule that is triggered on receipt of the designated event and uses the Send Email action to send the email.
The Send Email action configuration includes mandatory fields, such as the To and From email address. If the values vary by user and you want to include them as dynamic content when configuring the rule, ensure the values are included as part of the trigger event payload or set up in Swrve as a user property. If any of these values are the same for all the emails (for example,  From email), you can configure it manually when setting up the rule.

Marketing Email Lists

Marketing emails are bulk emails sent with minimal personalization to a set audience or list of users. Marketing emails are scheduled as opposed to triggered on a per-user basis. The target audience for a marketing email campaign are grouped as email lists. Management of such email lists and the scheduling of marketing email campaigns is done in SendGrid. Swrve is used only as a client to add or remove users from SendGrid-managed email lists.

For example, if you wanted to maintain an email list for users who have made in-app purchases, for retargeting purposes, you could create an email list called high_value_mobile_users in SendGrid and add users to the list (from Swrve) as and when the user makes their first purchase. Likewise, if the user opts out of receiving emails via an in-app message, the same user may be removed from an existing email list.

The action of removing or adding a user’s email is triggered on receipt of a related event. In the above example, the arrival of the purchase event or the email_opt_out event could be used as a trigger in a Swrve Amplify rule to implement the required list management behavior. There are two main steps involved in managing an email list via the SendGrid adaptor:

  1. Create a custom event in the Swrve SDK for the user action that you want to use to trigger the subscribe or unsubscribe action.
  2. Create an Amplify rule that is triggered on receipt of the designated event and uses the Subscribe User or Unsubscribe User action to manage the email list.
The Subscribe/Unsubscribe User action configuration includes the mandatory field: email address. The email address value should be included as part of the trigger event payload or stored in Swrve as a user property to configure the rule.

Update User Properties

The SendGrid adaptor sends email delivery and engagement events to Swrve, which you can use as part of your campaign engagement analysis or to trigger actions in Swrve. For example, if a customer unsubscribes to an email list, use the receipt of the Unsubscribe event to trigger a Swrve Amplify rule that updates the value of a user property called email_unsubscribed to true. You could then target those users with a push notification instead.


Adaptor Configuration

Step 1: To access the configuration settings, on the SendGrid Adaptor card, click Configure.

Step 2: Complete the following fields as required:

Field Description
Mail API Key The SendGrid API key for transactional emails. If you do not include a Marketing API key, this key is also used for the Marketing actions (Subscribe and Unsubscribe Users).
Marketing API Key The SendGrid API key for marketing emails. (Optional)

Step 3: To save the configuration settings, click Save.

After you click Save, the status of the Adaptor changes to Active and the Deactivate button is available. If you Activate or Deactivate the adaptor at any time, the changes apply to both the outbound and inbound actions.


Rule Configuration

This section describes the fields that are included when creating a new rule using the selected action. For most fields, you have the option to manually enter the value or to select a user property from the list to have Swrve automatically populate the value when the rule is processed. For more information on rules, see Creating Amplify Rules.

Send Email

Use the Send Email action to trigger a template-based email that is sent from SendGrid. Complete the following fields to include the values required to send the email.

Field Description
Template ID The email template the email should use. Email templates are managed in SendGrid.
To Comma separated list of recipient email addresses.
From Email The sender’s email address.
From Name The sender’s name.
Subject The subject of the email message. (Optional)
Text Body The plain text content of the email message. (Optional)
HTML Body The HTML content of the email message. (Optional)
Category The email category the email should be tagged under. Email categories are maintained in SendGrid. (Optional)
Advanced
BCC BCC recipient email address. (Optional)
Date The date used in the email header. The date must be coded in RFC 2822 format. (Optional)
Substitutions Substitutions are used to personalize the email template with user-specific values. Each substitution tag is associated with a list of replacement text for that tag in the email template body.
Unique Arguments The unique identifiers that SendGrid should send in the email engagement data postback, so the engagement metrics can be associated with the right Email Send operation.

Subscribe User

The Subscribe User action adds a specific user to an email list that is maintained in SendGrid. Complete the following fields to include the values required to add the user to an email list.

Field Description
Recipient List The name of the email list to which the user’s email address will be added.
Email The user’s email address.
First Name The user’s first name.
Last Name The user’s last name.

Unsubscribe User

The Unsubscribe User action removes a specific user from an email list that is maintained in SendGrid. Complete the following fields to include the values required to remove the user from an email list.

Field Description
Recipient List The name of the email list from which the user’s email address will be removed.
Email The user’s email address.

Inbound Actions

The SendGrid inbound adaptor uses webhooks with the SendGrid system to receive asynchronous email delivery and engagement events. The webhooks are set up when you activate the SendGrid adaptor. SendGrid sends the following events to Swrve:

Event DESCRIPTION
Bounced Receiving server could not or would not accept message.
Link Clicked Recipient clicked on a link within the message. You need to enable Click Tracking to receive this type of event.
Deferred Recipient’s email server temporarily rejected message.
Delivered Message has been successfully delivered to the receiving server.
Dropped The message was dropped due to one of the following reasons: Invalid SMTPAPI header, Spam Content (if spam checker app enabled), Unsubscribed Address, Bounced Address, Spam Reporting Address, Invalid, Recipient List over Package Quota.
Opened Recipient has opened the HTML message. You need to enable Open Tracking to receive this type of event.
Processed Message has been received and is ready to be delivered.
Reported As Spam Recipient marked message as spam.
Unsubscribed Recipient clicked on message’s subscription management link. You need to enable Subscription Tracking to receive this type of event.
Group Unsubscribed Recipient unsubscribed from specific group, by either direct link or by updating preferences. You need to enable Subscription Tracking to receive this type of event.
Group Resubscribed Recipient resubscribed to specific group by updating preferences. You need to enable Subscription Tracking to receive this type of event.