CRM Sync Module - Sendgrid - An Introduction

Introduction & Capabilities

The Sendgrid CRM Sync Module aims to integrate the Siteglide CRM with an Email Marketing Platform, starting with Sendgrid.

The module can carry out the following actions taking the data from the Siteglide Admin and using it to update the e-marketing platform's data:

  • Creating custom fields automatically
  • Renaming custom fields if the name has been changed in Siteglide
  • Creating a Contact with CRM data
  • Updating a Contact
  • Adding a Contact to Lists
  • Removing a Contact from Lists
  • Deleting a Contact

It's also possible to use Liquid logic and parameters to modify which of these actions is taken at any one time.

At the present time, the module does not make use of webhooks to update Siteglide when something changes on the e-marketing provider. Any checks on the current state of data on the e-marketing provider are done when the module code is run by Siteglide.

The module is not intended at the current time to allow design and triggering of bulk emails from the Siteglide Admin itself. Instead, by syncing data to an e-marketing platform, it allows you to make the most of the no-code and low-code tools on that platform, powered by automated, up-to-date, data. Sendgrid for example allows automations to be triggered a certain amount of time after a contact is added to a specific list. The module's job is to add that contact to the list, Sendgrid then has everything it needs to run a wide range of automations.

Getting Started

The module is designed to require minimal code to set up- for many use cases, you only need to add a single line of code.

Setting up your API key

The first thing you will need to do to use this module is create an account with an e-marketing provider. For now, we only support Sendgrid, but please let us know if you have a feature request to support another. Please follow Sendgrid's own support for help getting this set up.

Once you're logged in, you need to create an API key.

The API key can be added to the module in the Siteglide Admin:

You're now ready to add some simple code.

The Liquid include

The module provides you with Liquid code which, when run, carries out a range of actions using the details of a single Siteglide CRM user.

{% include 'modules/module_132/v1/crm_sync', marketing_provider: 'sendgrid', action: 'add' %}

Parameters

The following parameters can be used to modify behaviour:

marketing_provider required

At the moment, as we only support Sendgrid, this should be set to sendgrid. In future this may allow others to be selected.

action - add | update_if_added | remove required

This parameter controls essentially whether you wish the contact to be added or removed from the system, however, its behaviour is further modified by the lists parameter.

If the lists parameter is not included: add will add the contact to the marketing provider; remove will delete the contact from the e-marketing provider.

update_if_added is similar to add, but is designed for use-cases where you do not know if the user in question has given consent to receive marketing material. It will not create a new contact, but if a contact with that email address already exists, it will update custom fields to the latest Siteglide CRM data.

lists

Setting this parameter further modifies the behaviour of the previously discussed action parameter.

lists can be set to a comma-separated list of strings, where each string is an exact spelling to the name of a list in Sendgrid e.g.

{% include 'modules/module_132/v1/crm_sync', marketing_provider: 'sendgrid', action: 'add', lists: 'English Language Newsletter,Food and Recipes' %}

The above example will add the contact to both lists.

Unlike custom-fields, lists cannot be automatically created by the module API. They must be manually created in the Sendgrid portal first.

If the lists parameter is set: add will both add the contact and add them to all of the given lists. remove will remove the contact from all given lists, but will not delete them as a contact.

If you do wish to delete the contact completely, remove the lists parameter.

reserved_fields

The module automatically creates custom fields when you use the code to sync a contact, but Sendgrid also has "reserved fields" for storing data. The module will fill in some reserved fields automatically, like name and email address. But others will not be filled in automatically.

You can use the reserved_fields parameter to map Siteglide data into those reserved fields (optionally). To do this, first use the parse_json tag from platformOS or equivalent to create a liquid object, where the keys are exact matches for sendgrid reserved field names, and the values can be anything- hardcoded or dynamic Liquid data. Then pass the object in as the value of the parameter.

{% parse_json reserved_fields %}
  {
    "Address Line 1": "8 Tranquility Base",
    "Address Line 2": form.properties.form_field_3_2
  }
{% endparse_json %}
{% include "modules/module_132/v1/crm_sync", marketing_provider: "sendgrid", action: 'add', reserved_fields: reserved_fields %}

email

In most cases, adding the email parameter is unecessary as it will default to the value of {{form.properties.email}} which would be available inside a Siteglide automation for example.

However, if your use case requires running the code in a situation where this is not available, you can pass in the email address as a string instead:

{% include "modules/module_132/v1/crm_sync", marketing_provider: "sendgrid", action: 'add', email: 'example@example.com' %}

Examples

User consent can be captured on a form, using a checkbox or other field.

You can then use the data from this field to dynamically change the action parameter.

In this example, our form has the id form_1 and we have a custom radio field form_field_1_1. The code is contained within an automation so that we have access to the field's new data after the form submission.

HTML - inside the Siteglide Form

<fieldset>
  <legend>Would you like to be added to our mailing list?</legend>
  <input id="consent_true" type="radio" value="true" name="form[property_attributes][form_field_1_1]">
  <label for="consent_true">Yes please sign me up!</label>
  <input id="consent_false" type="radio" value="false" name="form[property_attributes][form_field_1_1]">
  <label for="consent_false">No thanks</label>
</fieldset>

Liquid - Inside the triggered automation after submission

{% if form.properties.form_field_1_1 == 'true' %}
  {% assign action = 'add' %}
{% else %}
  {% assign action = 'remove' %}
{% endif %}
{% include "modules/module_132/v1/crm_sync", marketing_provider: "sendgrid", action: action %}

Note, using a custom field that is not a CRM custom field means it is fire & forget. Using a CRM custom field will record this value for later. We recommend not fully relying on consent stored in a custom field on the contact and instead removing the contact if consent is withdrawn as in the example above.

Adding to lists depending on preference

Similar to the example above, you can also make the lists parameter dynamic based on the users' preferences:

HTML - inside the Siteglide Form

<fieldset>
  <legend>What kind of emails do you like receiving?</legend>
  <input id="fashion" type="checkbox" value="true" name="form[property_attributes][form_field_1_2]">
  <label for="fashion">Fashion</label>
  <input id="music" type="checkbox" value="false" name="form[property_attributes][form_field_1_2]">
  <label for="music">Music</label>
</fieldset>

Liquid - Inside the triggered automation after submission

{% assign lists = form.properties.form_field_1_2 | join: ',' %}
{% include "modules/module_132/v1/crm_sync", marketing_provider: "sendgrid", action: 'add', lists: lists %}

Further reading

What kind of data can I store on a contact?

When a contact is synced by the module code, it will send across all CRM custom fields across to the contact on the e-markerting provider. It will only do so if it is possible for it to automatically create remote custom fields to store these.

It will not send across data that is collected in the form case, but not directly in the CRM. That is, unless you use the reserved_fields parameter to manually send one of these across to populate a reserved field.

There are also some limitations on CRM custom fields of certain data-types. Sendgrid at the time of writing only supports 3 data-types date, text or number. Siteglide supports many more.

When syncing Siteglide CRM custom fields to Sendgrid then, the data is simplified so that it matches one of these approved types. The main types of field this affects is arrays e.g. a multi-select datasource will be converted to a comma-separated string.

You can use this array-like data in Sendgrid, for example in the mutli-dropdown field favourite letters with data A,B,C, you can create a segment which captures that contact using the rule contains B.

We recommend filling out a form to submit test data across to the e-marketing provider first and experiementing with the data you send across to see how it is represented and how it can be used.

Datasources are not supported, as sending across relational database IDs would have no meaning on the other platform.

When to trigger a sync?

In most use-cases, the best time for the module to take action is after a form submission, at the moment where the user is "live" on the site, giving consent to receive marketing emails. Commonly, it would therefore be included in a Siteglide Automation, or a Siteglide Form Confirmation Page. In both of these cases, you'd already have access to data concerning a specific contact which the module code can use.

Sometimes you may trigger the module code at a different time when the user is not "live" on the site, interacting with forms. For these use-cases, we've provided the option of setting the action parameter to update_if_added, see below. This allows you to sync data of only users who have already consented to be included as a contact.