In This Article:

    Engage API: Email Results

    In This Article:

      The API provides the ability to retrieve email activity data so that integrations or third-parties can use that data for segmentation/scoring externally. For instance, when invoked, Salesforce customers have a way to pull back data without necessarily storing it in Salesforce and creating storage concerns.

      Method
      End Point
      Detail
      POST /api/integration/ext/v1/emails/individualResults Provides the ability to acquire individual email result data.

      All calls listed above require that the API token be sent in the HTTP header using the parameter name authToken=<your_auth_token>. The request body format is as follows:

      {

      "payload": {

      "cursor": "2b49e8ee-5202-4712-b528-1237af435a95",

      "type": "CommSeries",

      "id": "0e5d63f7-1bfe-4d1e-a581-e2cd06f9db87",

      "contentId": "e4235a24-1dff-40ec-a6d9-924b4eac6d1a" 

      }


      }

      For email blasts, include only id param. For email series, include id and content id params.

      Parameter
      Location
      Mandatory/Optional
      Description

      cursor

      payload optional An optional value that is used for pagination only. Don't need to add this param for the first iteration. All other requests should include this param if pagination is needed. This value will be returned in the response payload. Need to copy this value from the last record in the response.

      id

      payload

      mandatory

      Required field. Email id to retrieve - 36 character UUID
      type payload mandatory

      2 possible values: CommSeries | Email

      CommSeries - if id belongs to email series

      Email - if id belongs to email blast

      contentId payload optional Email Series Message Id - 36 character UUID. Used to get individual email results data by specific message in email series.

       

      Search Endpoint

      Email and Email Series can be retrieved by providing a date range and a specific type of email activity.

      Email Activity Types

      Type

      Description

      Email Used for searching for blasts
      CommSeries

      Used for searching series

      The end point to invoke for searching emails is:

      POST /api/integration/ext/v1/emails/search

      All calls require that the API token be sent in the HTTP header using the parameter name authToken=<your_auth_token>. Include your search criteria within the body of the request as well formatted JSON.

      The request body format is as follows:

      {"payload":{
        "publishedFrom":"2015-04-26T11:49:24.905Z",
        "publishedTo":"2019-12-31T11:49:24.905Z",
      "type" : "Email",
      "offset":0,
      "count":10}
      }
      Parameter
      Location
      Mandatory/Optional
      Description
      publishedFrom payload mandatory

      Date from to retrieve emails - ISO_8601 formatted String with a GMT timezone

      publish date - for email series

      scheduled date - for email blasts

      publishedTo payload optional

      Date to retrieve emails - ISO_8601 formatted String with a GMT timezone

      publish date - for email series

      scheduled date - for email blasts

       

      type payload

      mandatory

      The types of emails to search for - this is an required parameter that is applicable for retrieving emails using the modifiedFrom or/and modifiedTo parameters.

      Value must be one of the following:

      • Email
      • CommSeries
      offset payload optional Starting count at which to retrieve emails- supports pagination and is only applicable when modifiedFrom and modifiedTo searching is used
      count payload optional Number of emails to retrieve - supports pagination and is only applicable when modifiedFrom and modifiedTo searching is used

       

      Request Example

      Description
      Body
      Get email blasts since a specific date
      {"payload":{
        "publishedFrom":"2015-04-26T11:49:24.905Z",
        "type" : "Email",
        "offset":0,
        "count":10}
      }
      Get series within a date range
      {"payload":{
        "publishedFrom":"2015-04-26T11:49:24.905Z",
        "publishedTo":"2019-12-31T11:49:24.905Z",
        "type" : "CommSeries", 
        "offset":0,
        "count":10}
      }

       

      Response Body Format

      {
          "id": "99f70525-6d2d-411c-a3c3-7ab7eda3a25f",
          "timestamp": "2019-03-04T11:47:37.204Z",
          "header": {
              "processingTime": 508,
              "serverId": "dev-hqapp1.ignite.net"
          },
          "payload": {
              "total": 2,
              "offset": 0,
              "emailActivities": [
                  {
                      "id": "34774086-ee8b-42e4-a6d0-4afcaf43ca30",
                      "topic": "General",
                      "name": "new manual",
                      "description": "rthrt",
                      "publishDate": "2017-11-15T18:36:16.646Z",
                      "components": [
                          {
                              "contentId": "9a666d5a-a86d-4ddf-a24d-4d45188cc6b2",
                              "messageNumber": "0"
                          }
                      ]
                  },
                  {
                      "id": "dccae6f7-1ab9-4607-ac0c-dfbd07e56fbc",
                      "topic": "General",
                      "name": "Test predemo 1234",
                      "description": "",
                      "publishDate": "2017-11-27T21:46:14.883Z",
                      "components": [
                          {
                              "contentId": "a537df44-041d-46cd-b17c-444caee97fcf",
                              "messageNumber": "1"
                          }
                      ]
                  }
              ],
              "count": 2
          }
      }
      

       

      List of fields in response for blasts by requirements

      Field
      Example
      Notes
      Field
      Example
      Notes
      id 9b22ccbf-cf42-4729-9aae-95b6ac1a749c Unique ID of the Email Blast
      name Save the Whales Email Blast Reference Name
      description A message to save the whales Email Blast Description
      scheduleTime 2018-10-12_16:37_EDT Time Sent
      publishDate 2018-10-12_16:37_EDT Date Published
      topic Fundraising Topic Assigned

       

      List of fields in response for series by requirements:

      Field
      Example
      Notes
      id 92f6efc3-4db6-4e6c-9dce-7aba79654654 Email Series Unique Engage ID
      name Welcome Series Email Series Reference Name
      description Our main welcome series. Email Series Description
      publishDate 2018-10-12_16:37_EDT Date Published
      topic Fundraising

      Topic Assigned

      components

      [ {
      "contentId": "cef1ea50-d9f0-4050-95b4-ee64eafd0459",
      "messageNumber": "1"}]

      List of messages for email series

       

      List of fields in response for series components by requirements:

      Field
      Example
      Notes
      contentId cef1ea50-d9f0-4050-95b4-ee64eafd0459 Email Series Message Id
      messageNumber 1 Email Series Message Order Number in the sequence
       

      Request Examples

      Description
      Body
      Get email blast activities by provided email id (first iteration)
      {

      "payload":{

      "id": "0e5d63f7-1bfe-4d1e-a581-e2cd06f9db87",

      "type":

      "Email"

      }

      }
      Get email blast activities by provided email id with pagination
      {

      "payload": {

      "cursor": "2b49e8ee-5202-4712-b528-1237af435a95",

      "type": "Email",

      "id":"0e5d63f7-1bfe-4d1e-a581-e2cd06f9db87"

      }

      }
      Get email series activities by provided email id and content id
      {

      "payload": {


      "cursor": "2b49e8ee-5202-4712-b528-1237af435a95",

      "type":"CommSeries",

      "id":"e4235a24-1dff-40ec-a6d9-924b4eac6d1a",

      contentId": "cef1ea50-d9f0-4050-95b4-ee64eafd0459"

      }


      }

       

      Response Body Format

      The response body format is as follows. All data provided in the request will be returned in the response. Only the most recent 1000 values per one request are returned by default and cannot be customized.

      {
      "id": "49a75035-3ad7-4de3-8080-52da6243f70c",
      "timestamp": "2019-03-12T12:19:15.264Z",
      "header": {
      "processingTime": 3654,
      "serverId": "test-hqapp2.ignite.net"
      },
      "payload": {
      "individualEmailActivityData": [
      {
      "id": "1039ca63-4403-4de0-bc5f-5362fd4e0569",
      "cursor": "2138d51c-2e89-4397-964a-6638eb6a1148_3190502",
      "name": "api2",
      "recipientsData": {
      "recipients": [
      {
      "supporterId": "93539db5-7e90-490f-9c66-1911e0331181",
      "supporterEmail": "pei.druzey1a@mailosaur.io",
      "firstName": "Oleg",
      "lastName": "Lauta",
      "country": "US",
      "state": "MN",
      "city": "Saint Cloud",
      "timeSent": "2019-03-05T14:47:16.203Z",
      "splitName": "Split A",
      "status": "Delivered",
      "opened": true,
      "clicked": true,
      "converted": true,
      "unsubscribed": false,
      "firstOpenDate": "2019-03-05T15:33:07.993Z",
      "numberOfLinksClicked": "1",
      "conversionData": [
      {
      "conversionDate": "2019-03-05T15:33:49.467Z",
      "activityType": "P2PEvent",
      "activityName": "teams collision",
      "activityId": "3486af9e-f0b9-4429-8d4e-8202262d4e3f",
      "amount": "10.0",
      "donationType": "OneTime"
      }
      ]
      },
      {
      "supporterId": "d25b96e3-3c28-45e6-8b30-3762dedf1f81",
      "supporterEmail": "pe.druzey1a@mailosaur.io",
      "firstName": "Pe",
      "lastName": "Pe",
      "country": "US",
      "state": "MN",
      "city": "Saint Cloud",
      "timeSent": "2019-03-05T14:47:16.213Z",
      "splitName": "Split A",
      "status": "Sent",
      "opened": false,
      "clicked": false,
      "converted": false,
      "unsubscribed": false,
      "numberOfLinksClicked": "0"
      }
      ],
      "total": 2
      }
      }
      ]
      }
      }

      Below, you can find a table of response fields with examples and descriptions.

      Field
      Example
      Notes
      salesforceId 006A000000bxTRu Contact ID
      supporterId 9b22ccbf-cf42-4729-9aae-95b6ac1a749c Supporter Unique Engage ID
      externalId 1112 Supporter External ID
      supporterEmail ccraig+cat@salsalabs.com Supporter Email Address
      firstName Chris Supporter First Name
      lastName Craig Supporter Last Name
      country US Supporter Country
      state MD Supporter State
      city Bethesda Supporter City
      id 92f6efc3-4db6-4e6c-9dce-7aba79676e09 Email Blast Unique Engage ID / Email Series Unique Engage ID
      contentId 92f6efc3-4db6-4e6c-9dce-7aba79673242 Email Blast Content ID / Email Series Content ID
      name Save The Whales! Email Blast Reference Name / Email Series Reference Name
      splitName Split A

      If Split Test, Test Version

      emailSeriesName Message A Email Series Component Name
      timeSent 2018-10-12_16:37_EDT Time Sent to Supporter
      status Delivered Delivery Status
      opened TRUE Supporter Open
      clicked TRUE Supporter Click
      converted FALSE Supporter Converted (Limited to Salsa Forms)
      unsubscribed FALSE Supporter Unsubscribed
      firstOpenDate 2018-10-12_16:38_EDT Supporter First Open
      numberOfLinksClicked 2 Supporter Number of Clicks
      bounceCategory Hard Bounce

      If Bounced, Bounce Category (e.g., Hard Bounce). Will be one of:

      • Hard Bounce
      • Soft Bounce
      • Blocked
      • Unknown
      • Spam
      • Complaint
      • Other
      bounceCode User Unkown

      If Bounced, Bounce Code (e.g., bad-mailbox). Will be one of:

      • bad-mailbox
      • bad-configuration
      • invalid-sender
      • routing-errors
      • bad-domain
      • protocol-errors
      • inactive-mailbox
      • no-answer-from-host
      • quota-issues
      • policy-related
      • bad-connection
      • relaying-issues
      • message-expired
      • virus-related
      • content-related
      • spam-related
      • other


      List of fields for conversions as a nested JSON in response for email blast/email series activities by requirements...

      Field
      Example
      Notes
      conversionDate 2017-06-14_15:33_EDT Conversion Date
      activityType Fundraising

      Type of the Activity. Will be one of:

      • SUBSCRIPTION_MANAGEMENT
      • SUBSCRIBE
      • FUNDRAISE
      • PETITION
      • TARGETED_LETTER
      • TICKETED_EVENT
      activityName Save the Oceans - Multi-step Fundraising Page Activity Name
      activityId b5644ec9-51ff-4ddd-900c-d9e10cabfd27 Activity ID
      amount $50.00 If Donation, Amount Donated
      donationType OneTime

      If Donation, Donation Type. Will be either...

      • ONE_TIME
      • RECURRING 
       
       
       
      Was this article helpful?
      0 out of 0 found this helpful
      Have more questions? Submit a request

      Comments

      0 comments

      Article is closed for comments.