Xperience SendGrid Integration

This integration allows the dipatching of all Xperience emails from the Email queue to SendGrid using their reliable Web API. Using the Web API offers faster email processing, so you can squeeze out the most performance while sending those big marketing campaigns! The sending process is highly customizable and you can even use standard Xperience event handlers to react to SendGrid events such as email drops and bounces, or opens and clicks.

Set up the environment

Install the NuGet package

1. Install the Kentico.Xperience.Twilio.SendGrid NuGet package in both the administration and the live-site projects.
2. Access your SendGrid account, or sign up for a new account here (it's free to start!).
3. Go to Settings → API Keys and click the Create API Key button.
4. Create an API key with Restricted Access and grant the following permissions:
   • Mail Send: Full access
   • Suppressions: Full access
5. Copy the API key and add the following to your administration project's web.config, in the appSettings section:

<add key="SendGridApiKey" value="<API key>" />

6. Add the API key to your live-site project's configuration file:

• Core - appSettings.json

"xperience.twilio.sendgrid": {
  "apiKey": "<API key>"
}

• MVC - web.config

<add key="SendGridApiKey" value="<API key>" />

7. In the live-site project's startup code, call the AddSendGrid() extension method:

public void ConfigureServices(IServiceCollection services)
{
    services.AddSendGrid(Configuration);
}

(Optional) Import the custom module

You may choose to import a custom module into your Xperience administration project to enable additional functionality:

• SendGrid Event Webhooks
• Suppression management

If you would like to use these features, follow these steps to install the custom module:

1. Open your administration project in Visual Studio.
2. Download the latest "Kentico.Xperience.Twilio.SendGrid" ZIP package from the Releases.
3. In the Xperience administration, open the Sites application.
4. Import the downloaded package with the Import files and Import code files settings enabled.
5. Perform the necessary steps to include the following imported folder in your project:
   • /CMSModules/Kentico.Xperience.Twilio.SendGrid

SendGrid email sending

After importing and configuring the integration, all Xperience emails will be dispatched via SendGrid's Web API. When SendGrid successfully receives the email for further processing, the Xperience email will be removed from the Email queue and archived or deleted. If SendGrid cannot successfully queue the email for processing, the Xperience email will remain in the email queue with an error message.

Emails are dispatched to SendGrid by the ISendGridEmailSender, of which you can find the default implementation here. If you would like to customize email sending, you can create your own implementation of ISendGridEmailSender and register it with higher Priority:

[assembly: RegisterImplementation(typeof(ISendGridEmailSender), typeof(MyCustomSendGridEmailSender), Lifestyle = Lifestyle.Singleton, Priority = RegistrationPriority.Default)]
namespace MySite.Twilio.SendGrid {
    /// <summary>
    /// Custom implementation of <see cref="ISendGridEmailSender"/>.
    /// </summary>
    public class MyCustomSendGridEmailSender : ISendGridEmailSender {
        ...
    }
}

SendGrid mail configuration

Within SendGrid's Settings, you can globally configure many mail settings and tracking settings. Most of those settings can also be set using SendGrid's API, as seen in the default implementation of ISendGridConfigurationProvider here. If you would like to fine-tune these settings per email, per marketing campaign, or per Xperience site, you can register your own implementation of ISendGridConfigurationProvider with higher Priority:

[assembly: RegisterImplementation(typeof(ISendGridConfigurationProvider), typeof(MyCustomSendGridConfigurationProvider), Lifestyle = Lifestyle.Singleton, Priority = RegistrationPriority.Default)]
namespace MySite.Twilio.SendGrid {
    /// <summary>
    /// Custom implementation of <see cref="ISendGridConfigurationProvider"/>.
    /// </summary>
    public class MyCustomSendGridConfigurationProvider : ISendGridConfigurationProvider {
      ...
    }
  }

This could be helpful if, for example, you want to use a different IP Pool for each Xperience site. Or, if you want tracking to be enabled only for certain emails.

Handling SendGrid Event Webhooks

Note Requires installation of the custom module.

SendGrid has the ability to send webhooks to your Xperience administration website when certain events occur. SendGrid event handling is implemented via standard Xperience event handling, so you can handle SendGrid event webhooks like this:

SendGridEvents.Bounce.After += HandleSendGridBounce;

You can view the available events in the SendGridEvents class. To enable event webhook handling in your Xperience administration website:

1. In SendGrid, open Settings → Mail Settings → Event Webhook.
2. Set the following values:

• Authorization Method: None.
• HTTP Post URL: https://[your Xperience CMS]/xperience-sendgrid/events.
• Events to be POSTed to your URL: Select any events you'd like to handle.
• Event Webhook Status: Enabled.

3. In Mail settings, click Signed Event Webhook Requests.
4. Enable Signed Event Webhook Request Status and copy the Verification Key.
5. In the CMS project's web.config appSettings section, add the following setting:

<add key="SendGridWebhookVerificationKey" value="<Verification key>"/>

Suppression management

Note Requires installation of the custom module.

Within the Xperience Email marketing application you will find a new tab called "Suppressions." This interface allows you to manage Xperience and SendGrid email suppressions for subscribers of the newsletter or email campaign. For newsletters, the tab can be found when editing the newsletter. For email campaigns, it appears when editing an individual email of the campaign.

The Bounced in SendGrid column indicates whether the email is listed under SendGrid's Suppressions → Bounces list. The Bounces in Xperience column lists the number of bounces recorded in the Xperience database, and will be red if the number of bounces exceeds the "Bounced email limit" setting in Settings → On-line marketing → Email marketing. Using the checkboxes and drop-down menu at the bottom of the grid, you can reset these bounces to ensure that your emails are delivered to the recipients.

Feedback & Contributing

Did you find a bug, have a feature request, or just want to let us know how we're doing? Create a new GitHub Issue and tell us about it! If you'd like to contribute to the project, check out CONTRIBUTING.md to get started.

License

Distributed under the MIT License. See LICENSE.md for more information.

Questions & Support

See the Kentico home repository for more information about the product(s) and general advice on submitting questions.