Email Opt-Out Preference APIs

Last updated
Save as PDF

This article explains how you can create, update, and fetch Email Opt-Out Preferences using APIs.

IMPORTANT: This article describes a GA-ready feature, but the feature is not enabled by default. If you would like early access, please submit a support ticket. If you choose not to access this feature early, they'll be available in your tenants automatically with the upcoming major release.

Introduction

The Email Opt-Out API helps you create, update and fetch Email Opt-Out. These external APIs allow integration with other CRMs to sync opt-out preferences into Gainsight.

Authorization

The API access is controlled using a unique Access Key. Contact your Gainsight Admin to get an access key to the Gainsight tenant to which you want to send REST API requests. For more information on how to generate or share an access key, refer to the Generate API Access Key article.

Once you have your access key, you need to pass the access key as part of the request header “accesskey” for all of your API requests into Gainsight.
Note: The access key is permanent and does not expire.

Headers

Key	Value
Accesskey	NA. For more information on how to generate an access key, refer to the Authorization section.
Content Type	JSON

Throttling Limits

The following are the overall recommended External API limits in Gainsight (The exact limits can vary based on your package):

Key	Value
Synchronous API Calls	100 API calls per minute / 50,000 API calls per day
Asynchronous API Calls	10 calls per hour / 100 per day

Update Email Opt Out Preferences API

Method

POST

Endpoint URL

https://v1/communications/es/opt-out/preference/save

Sample Request Body

Request 1: With RecipientId of email log [Recommended since RecipientID is required to update the JO analytics unsubscribe count]

{
  "identifiers": {
    "RecipientId": "<Gainsight Email Recipient Id>"
  },
  "optOutPreferences": [
    {
      "categoryId": "1I0049S37DGCWLOCQ1VBQY196AV7ZLBQAAWY",
      "categoryCode": null,
      "optOutReason": "I no longer want to receive these emails.",
      "optOut": true
    },
    {
      "categoryId": null,
      "categoryCode": "Customer Success Communication",
      "optOutReason": null,
      "optOut": true
    },
    {
      "categoryId": null,
      "categoryCode": "survey",
      "optOutReason": null,
      "optOut": false
    }
  ]
}

Request 2: With email Id / any other field of person

{
  "identifiers": {
    "emailId": "person1@xyz.com"
  },
  "lookups": {
    "PersonId": {
      "fields": {
        "emailId": "Email"
      },
      "lookupField": "Gsid",
      "objectName": "Person",
      "multiMatchOption": "FIRSTMATCH",
      "onNoMatch": "ERROR"
    }
  },
  "optOutPreferences": [
    {
      "categoryId": "1I0049S37DGCWLOCQ1VBQY196AV7ZLBQAAWY",
      "categoryCode": null,
      "optOutReason": "I no longer want to receive these emails.",
      "optOut": true
    },
    {
      "categoryId": null,
      "categoryCode": "Customer Success Communication",
      "optOutReason": null,
      "optOut": true
    },
    {
      "categoryId": null,
      "categoryCode": "survey",
      "optOutReason": null,
      "optOut": false
    }
  ]
}

Parameters

Parameter	Required/Optional	Data Type	Description
identifiers	Required	String	A String value in which you can resolve a person record by passing either the RecipientId or any field from the Person object (if using a field, corresponding lookup details must be provided).
categoryId	Either categoryId or categoryCode is required	String	A String value that contains a unique Opt Out Category ID.
categoryCode	Either categoryId or categoryCode is required.	String	A String value that contains a unique Opt Out Category Code.
optOutReason	Optional	String	A String value that contains the reason for email opt out.
optOut	Required	Boolean	A Boolean value where false means the user receives emails (opted in), and true means the user does not receive emails (opted out)
lookupField	Required	String	A String value that contains Gsid (lookup field name)
objectName	Required	String	A String value that contains object name Example: Person.
multiMatchOption	Required	String	A String value that has possible values as FIRSTMATCH and MARKASERROR.
onNoMatch	Required	String	A String value that shows ERROR if a provided input or condition does not match any existing records or criteria.

Sample Success Response

{
    "result": true,
    "errorCode": null,
    "errorDesc": null,
    "localizedErrorDesc": null,
    "requestId": "976c40a1-0cc4-4294-8226-19b04ac6f688",
    "data": {
        "categories": [
            "1I0049S37DGCWLOCQ1VBQY196AV7ZLBQAAWY",
            "1I0049S37DGCWLOCQ1Y3IDSVH32G7NHHL00A"
        ]
    },
    "message": null,
    "localizedMessage": null
}

Get Preference API