Integrating with SendGrid

You can quickly and easily integrate Commerce with SendGrid using the Integrations Hub in Commerce Manager. Integrating with SendGrid allows you to send emails to your customers when events in Commerce are triggered. For example, you can send a customer registration email when you create a customer in Commerce, or send an order confirmation email when an order is created.

An example of how an email is sent using a SendGrid integration is described below.

1. When an order is created, an order.created event is triggered.
2. Once an order.created event is received by the webhook, the integration begins to execute.
3. The integration:
   • Uses Init Flow to validate that your Commerce events are in the correct format and creates a Commerce webhook for each event.
   • Uses Main Flow to:
     • Consume the events.
     • Passes a SendGrid email Template ID so that SendGrid knows which email template to use.
     • Populates the fields configured in a SendGrid dynamic template with the values from Commerce.
     • Uses SendGrid V3 Mail Send API to send an email to your customer.

You must have completed the following tasks in SendGrid before configuring the integration in Commerce.

1. Created an account.
2. Verified your sender email addresses. This can be a single sender or inbox providers that you own in your domain.
3. Obtained a SendGrid API key with, at least, Mail Send access.

See SendGrid Documentation for more information.

Below is an overview of the steps you need to follow to integrate Commerce with SendGrid.

1. Make sure you have met the prerequisites. See Prerequisites.
2. Collect the setup information for SendGrid and Commerce. See Collecting Your Setup Information.
3. Create a dynamic template in SendGrid. See Creating Dynamic Templates in SendGrid.
4. Create the event mapping between Commerce and the SendGrid email template. See Configuring Event Mapping.
5. Create a SendGrid integration in Commerce Manager > Integrations Hub. See Configuring the SendGrid Integration.

Before you begin configuring your SendGrid integration in Commerce Manager, you need to collect the necessary setup information from SendGrid and Commerce Manager.

You need the SendGrid API Key ID which is the API Key for your SendGrid account. In SendGrid, API keys are found in Settings > API Keys.

Collect the following Commerce API keys. You can find this information in SYSTEM > Application Keys in Commerce Manager when logged in as a user with Seller Admin privileges.

Once you have created a dynamic template in SendGrid, you need to do the following. For more information, see SendGrid Documentation.

1. Add placeholders in your dynamic template for the data that you want to pass from Commerce to the email.
2. Make a note of the Template ID as you need this when configuring your SendGrid integration in Commerce Manager > Integrations Hub.

Each event mapping configuration is a set of parameters for a specific event type in Commerce. The event mapping configuration is stored as key + value pairs.

• An event key is the name of the Commerce event that triggers the event mapping configuration. For example, order.paid or order.created. See Observable events for a list of Commerce events.
• An event value is a JSON object that must contain a messagingProvider element and a dynamicFieldMapping element. The event value object can be:
  • A single object (if you want to send one email when a Commerce event is triggered).
  • An array of event value objects (if you want to send more than one email from SendGrid when a Commerce event is triggered).

The attributes and types for the messagingProvider object are defined in the following table.

The dynamicFieldMapping object uses JSONata as its query language.

The attributes and types for the dynamicFieldMapping object are defined in the following table.

Below is an example of a single messagingProvider object.

{
  "messagingProvider": {
    "templateId": "d-7fd1f0f905974f9abc9f8f44f883e0b5",
    "from": "customer-service@foo.com"
  },
  "dynamicFieldMapping": {
    "marketingImage": "http://example.com/static/value.png",
    "to": "$.payload.data.customer.email",
    "firstName": "$.payload.data.billing_address.first_name",
    "lastName": "$.payload.data.billing_address.last_name",
    "orderId": "$.payload.data.id",
    "orderTotal": "$.payload.data.meta.display_price.with_tax.formatted",
    "items": "$.payload.included.items[].{'name': name,'sku':sku, 'price': meta.display_price.with_tax.value.formatted}"
  }
}

Below is an example of an array of messagingProvider objects.

[
  {
    "messagingProvider": {
      "templateId": "d-5377hisuhf477h2hhbahd563gag5h",
      "from": "no-reply@foo.com"
    },
    "dynamicFieldMapping": {
      "marketingImage": "http://example.com/static/order-notification.png",
      "to": "customer-service@foo.com, jane.doe@example.com",
      "firstName": "$.payload.data.billing_address.first_name",
      "lastName": "$.payload.data.billing_address.last_name",
      "orderId": "$.payload.data.id",
      "orderTotal": "$.payload.data.meta.display_price.with_tax.formatted",
      "items": "$.payload.included.items[].{'name': name,'sku':sku, 'price': meta.display_price.with_tax.value.formatted}"
    }
  },
  {
    "messagingProvider": {
      "templateId": "d-7fd1f0f905974f9abc9f8f44f883e0b5",
      "from": "customer-service@foo.com"
    },
    "dynamicFieldMapping": {
      "marketingImage": "http://example.com/static/thank-you.png",
      "to": "$.payload.data.customer.email",
      "firstName": "$.payload.data.billing_address.first_name",
      "lastName": "$.payload.data.billing_address.last_name",
      "orderId": "$.payload.data.id",
      "orderTotal": "$.payload.data.meta.display_price.with_tax.formatted",
      "items": "$.payload.included.items[].{'name': name,'sku':sku, 'price': meta.display_price.with_tax.value.formatted}"
    }
  }
]

You can trigger an email to be sent from SendGrid using a custom event from a system that is external to Commerce. For example, you might have a Contact Us page where your customers can ask questions and you can email them in return. Custom events use HTTP POST to post to the webhook endpoint for the integration. The URL of the webhook endpoint is visible in either the SendGrid Email integration in Integrations Hub or within SYSTEM > Store Settings > Webhooks. You can configure your storefront to post an event to this webhook and trigger a custom event so that the integration causes a SendGrid email to be sent.

The fields that you define in your custom event object can be anything you want. For example, you may want to include subject, body and received_at fields, in addition to any Commerce data that needs to be sent to your SendGrid email template.

The attributes and types for custom event object are defined in the following table.

Below is an example a custom event object.

{
  "triggered_by": "custom.contact-us",
  "customer_email": "john.doe@example.com",
  "subject": "Question about Product ABC",
  "body": "Does it come in XS size?",
  "received_at": "2022-09-09T12:34:38.679Z",
  "configuration": {
    "secret_key": "ABC123ZY715XdZkAMrrsN410xSd99yir0WAECl7dij+M="
  }
}

Once you have:

• Met the prequisites.
• Collected your setup information.
• Created your dynamic templates in SendGrid.
• Configured your event mapping.

You are ready to configure the SendGrid integration in Integrations Hub.

1. In Commerce Manager, go to COMPOSER > Integrations Hub.

2. Under Email and SMS Integrations, click SendGrid Email. The SendGrid Email integration guides you through the steps you need to follow to complete the integration.

3. Click Configure. The Trigger details consist of the webhooks for the Init Flow and Main Flow. You do not need to change any of the information here.

   Do not configure any API keys for the webhooks. The webhooks are authorized using the configuration.secret_key value in the request body. Configuring an API key directly on the webhook results in a non-functional integration.

4. Click Next. The Configuration page is displayed.

5. Complete the information in the Configuration page and configure the following.

   • EPCC-Base-URL - Your Commerce API Base URL.
   • EPCC-Client-ID - Your Commerce Client ID.
   • EPCC-Client-Secret - Your Commerce Client Secret.
   • SendGrid-API-key - The SendGrid API Key ID which is the API Key for your SendGrid account.

6. In Event-Mapping, click + Add value.

7. In Key type the name of the Commerce event that, when triggered, causes an email to be sent from SendGrid. For example, order.created or customer.created.

8. In Value, copy the messagingProvider object that you want to use when the Commerce event is triggered.

   

9. Click + Add value to add as many key + value pairs as you want.

10. Click Finish. Your integration is enabled.

To add more event mappings to your SendGrid integration, go to Summary > Reconfigure.

In addition, from Summary, you can view, pause or delete your SendGrid integration.

If there is an update to the Commerce SendGrid Email integration, a message is displayed in Summary. Click Update to update your integration. You are walked through the steps to configure your integration.

You can test your Commerce payloads in Test.

You can debug any issues in Executions. Each time an event that triggers an email to be sent from SendGrid is executed, you can click on that execution. The Logs shows the output and any errors or warnings.

From Step Outputs, you can do the following.

1. Select Validate Event Mappings to see which events were properly formatted. Events that are not properly formatted are ignored and are, therefore, not shown.
2. Select EPCC Event Publish Trigger to see the code that was posted that triggered the email. This is useful if you want to check the code.
3. Select Apply Event Mapping to Request to see all the values that were sent to SendGrid.
4. Select Send Email via SendGrid to see the HTTP code and status text for the API response that sent the email to SendGrid.

Select Retry to initiate an execution again.