Skip to content
Arc XP
Product Documentation

SendGrid Email Service Provider Connector

Background

Many of our clients use ESP to effectively manage and execute email marketing campaigns, resulting in improved deliverability, engagement, and ultimately business growth. However, it may be a bit cumbersome for clients currently to manually connect Arc Subscriptions WebSocket events to their ESP. Today we will be showing how to create integration between Subscriptions and SendGrid using IFX Node.js implementations. This will allow clients to send transactional emails triggered by the Subscription events. Many of our clients may already have an ESP of choice for marketing purposes and this integration can be also extended to easily send emails with the existing ESP. 

Arc XP’s Subscriptions make setting up your email service provider (ESP) quick and painless with our extendable Connector. The Connector utilized IFX to create an integration between Subscriptions WebSocket events and SendGrid. Want to continue using your preferred ESP, just extend this Connector using this guide. You will be up and running quickly and then can move on to tailoring your marketing and transactional emails for your business.

Bookmark the IFX documentation for later reference.

Create an IFX integration

Full guide: Create and Manage Integrations

POST /admin/integration with the body:

{
  "integrationName": "my-integration-name",
  "description": "This integration will be used for special things.",
  "email": "{email address for alerts}",
  "runtime": "node"
}

Download a zip file of the bundled code

GET /admin/bundles/{integrationName}/download/{bundleName} to download the starter bundle. Unzip the bundle and use the preferred source control to store the code.

Subscribe to Events

Below is an example payload subscribing to the commerce:verify_email event:

POST /ifx/api/v1/admin/events/subscriptions

  {
    "eventName": "commerce:verify_email",
    "enabled": true,
    "integrationName": "my-integration-name"
  }

This should be done for each event that you’d like your integration to listen to.

Modify the Example Code

  • Download and unzip subssinglesite-esp-subssinglesite-1-0-0 2.zip

  • Copy the code in the src to the newly created repository. If you do not have access to this code, please submit an ACS request.

  • Follow the readme on the template code to install npm packages and run the local testing server

  • @sendgrid/mail needs to be installed on top of what is already on the template code

  • More details on running the app locally can be found here

  • For secrets and sensitive information such as the SendGrid API key, you should store these values by following this guide

  • For non-sensitive information, such as CDN_ENDPOINT, EMAIL_SENDER, and WEB_SITE_URL, these can be stored in the respective environments (.env.development, .env.sandbox, and .env.production)

  • You will need to update templateId used in each email handler with the values from dynamic templates from your SendGrid account as well as variables in the .env files

src/eventsHandlers/verifyEmailHandler.js
const sendEmail = require('../sendEmail');


const verifyEmailHandler = async (event) => {
    const msg = {
      to: event?.body?.email,
      from: process.env.EMAIL_SENDER,
      subject: 'Please verify your account',
      // Please update templateId with correct value
      templateId: 'd-db2624673d4c4d989474ecacd1a626b3',
      dynamic_template_data: {
        firstName: event?.body?.firstName,
        CDN_ENDPOINT: process.env.CDN_ENDPOINT,
        email: event?.body?.email,
        nonce: event?.body?.nonce
      }
    }


    await sendEmail(msg);
}


module.exports = verifyEmailHandler;

eventsRouter.json determines which event gets routed to a specific handler. For example, when commerce:verify_email event is triggered, logic inside the verifyEmailHandler will be executed.

src/eventsRouter.json
{
  "verifyEmailHandler": ["commerce:verify_email"],
  "emailVerifiedHandler": ["commerce:email_verified"],
  "userSignupHandler": ["commerce:user_sign_up"],
  "usersigninaddedHandler": ["commerce:user_sign_in_added"],
  "passwordresetrequestHandler": ["commerce:password_reset_request"] ,
  "passwordresetHandler": ["commerce:password_reset"],
  "magiclinksendHandler": ["commerce:magic_link_send"],
  "orderconfirmationHandler": ["commerce:finalize_payment", "commerce:order_confirmation"]
}

The events emitted by Arc Subscriptions include predefined data on these events but if you want some custom data, you can call developer API from the event handler to get the data and use those in the dynamic email template. For example, if the firstName was not provided, a developer can call a developer API with a PAT and use the result to populate the dynamic template.

src/eventsHandlers/verifyEmailHandler.js
const axios = require( 'axios');
const sendEmail = require('../sendEmail');


const verifyEmailHandler = async (event) => {


  const url = `${process.env.API_ENDPOINT}identity/api/v1/profile/${event?.body?.uuid}`
  const options = {
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${process. env. ARC_PAT}`
    }
  }


  const data = await axios get(url, options). then (res => res.data) .catch (e => console.error(e));


  const msg = {
    to: event?.body?. email,
    from: process. env. EMAIL_SENDER,
    subject: 'Please verify your account',
    templateId: 'd-db2624673d4c4d989474ecacd1a626b3',
    dynamic_template_data: {
      firstName: data?. firstName,
      CDN_ENDPOINT: process. env. CDN_ENDPOINT,
      email: event?. body?. email,
      nonce: event?. body?. nonce
    }
  }


  await sendEmail(msg);


}


module.exports = verifyEmailHandler;

Set up a SendGrid account

Use this link to get started with SendGrid.

Create an API key under the account.

Create dynamic templates to be used with different events

You’ll need template ids later in the guide.

The dynamic template uses Handlebars. {{}} can be used to insert variables and test data can be inserted to preview the email

Bundle, Deploy, Promote IFX Integration

Follow this guide to bundle, deploy and promote your integration.

Debugging and Testing