Managing audience subscriptions

Ortto’s subscription preference center allows customers to manage their subscriptions to the audiences they want to receive messages from. It is available for both SMS and Email.

The following describes an example of the email preference center as seen by the user.

When a user toggles on and off the options in a given audience, this activity toggles their subscription preference for that particular audience. This helps avoid customers unsubscribing from everything, since they have the option to opt-out of specific communications (i.e. audiences) instead of everything all at once.

Audiences will show up in the preference center if the Show this audience in the preference center as a subscription. option is selected for that audience in Ortto. If an audience is in this mode, then messages sent to that audience will have Unsubscribe from this list as an option instead of Unsubscribe.

Sometimes, you might want to change a person’s SMS and Email audience subscription via the API. Perhaps you offer these options to the customer in your app, or you simply want to provide them with other places to manage their subscriptions. Additionally when creating new audiences, you might want to programmatically subscribe people to them.

Getting the current subscriptions for people

curl --request POST 'https://api.ap3api.com/v1/person/subscriptions' \
     --header 'X-Api-Key: YOUR-CUSTOM-API-KEY' \
     --header 'Content-Type: application/json' \
     --data-raw '{
      "audience_id": "625f7213a914327aa1999b43",
      "people": [
        {
          "email": "chris@ortto.com"
        }
      ]
    }'

Here’s an example response for the current subscription status:

{
  "people": [
    {
      "person_status": "merged",
      "person_id": "00624536230993474f078a00",
      "subscriptions": [
        {
          "audience_id": "625f7213a914327aa1999b43",
          "audience_name": "Weekly updates",
          "member_from": "2022-04-20T02:38:11Z",
          "subscribed": true,
          "subscribed_from": "2022-04-20T02:38:11Z",
          "sms_opted_in": false
        },
        {
          "audience_id": "6241681069639ee210f8a298",
          "audience_name": "Subscribers",
          "member_from": "2022-03-31T05:03:31Z",
          "subscribed": true,
          "subscribed_from": "2022-03-31T05:03:31Z",
          "sms_opted_in": false
        },
        {
          "audience_id": "6241681069639ee210f8a29a",
          "audience_name": "Engaged subscribers",
          "member_from": "2022-03-31T12:56:14Z",
          "subscribed": true,
          "subscribed_from": "2022-03-31T12:56:15Z",
          "sms_opted_in": false
        }
      ],
      "email_permissions": true,
      "sms_permissions": false
    }
  ]
}

People are not auto-subscribed to SMS for compliance reasons. Using the API is good way to opt-in your customers to SMS if you want to be able to contact all of them.

Getting all current members and subscribers of an audience

Learn more about how to do this in Retrieving audience members and subscribers (from audiences).

Subscribing people to an audience (email and SMS)

https://api.ap3api.com/v1/audience/subscribe

Example of subscribing and unsubscribing people to an audience for email by email

In the following example, person1@example.com is subscribed to the audience with ID 61380ac92593ecf2de4fd705 for email and person2@example.com is unsubscribed from that same audience for email. You can send subscription preferences for up to 1000 people in the same request for the same audience. Specify async: true if you want the system to return as soon as you request is accepted, rather than waiting for it to complete.

curl --request PUT 'https://api.ap3api.com/v1/audience/subscribe' \
     --header 'X-Api-Key: YOUR-CUSTOM-API-KEY' \
     --header 'Content-Type: application/json' \
     --data-raw '{
      "audience_id": "61380ac92593ecf2de4fd705",
      "people": [
        {
          "email": "person1@example.com",
          "subscribed": true
        },
        {
          "email": "person2@example.com",
          "subscribed": false
        }
      ],
      "async": true
    }'

The audience_id comes from the Ortto UI. You can find it by navigating to the audience you wish to reference and copying the ID from the URL. For example, if you are looking at an audience and the URL is https://ortto.app/myinstance/audiences/60a350243945d90a792f830c/performance?from=audiences-index&key=- then the audience_id is 60a350243945d90a792f830c.

Example of subscribing and unsubscribing people to an audience for email by external_id

In the following example, the person with external_id of 7819 is subscribed to the audience with ID 61380ac92593ecf2de4fd705 for email. external_id is a field on people in Ortto’s CDP which allows you to track them by your own ID. When specifying external_id in a person merge update you might see it as str::ei, this is that field.

curl --request PUT 'https://api.ap3api.com/v1/audience/subscribe' \
     --header 'X-Api-Key: YOUR-CUSTOM-API-KEY' \
     --header 'Content-Type: application/json' \
     --data-raw '{
      "audience_id": "61380ac92593ecf2de4fd705",
      "people": [
        {
          "external_id": "7819",
          "subscribed": true
        }
      ],
      "async": true
    }'

If you update subscriptions without "async": true, you will get a response like the following.

{
  "audience_id": "625f7213a914327aa1999b43",
  "people": [
    {
      "person_status": "merged",
      "status": "subscribed",
      "person_id": "00624536230993474f078a00"
    }
  ]
}

Note that the "status": "subscribed" pertains to this person’s audience subscription, as opposed to their global email or SMS opt-in status. To find out the full status of subscribers, use the endpoints described here: Retrieving audience members and subscribers

Example of subscribing and unsubscribing people to an audience for email by person_id

In the following example, the person with person_id of 006046bbb2284e24ae0b0e00 is unsubscribed from the audience with ID 61380ac92593ecf2de4fd705 for email. person_id is a field on people in Ortto’s CDP which uniquely identifies them. You can get the person ID either with the (LINK TO PERSON GET FUNCTION), or from the URL for that person in the CDP, e.g. https://ortto.app/myinstance/cdp/people/006046bbb2284e24ae0b0e00/activities where 006046bbb2284e24ae0b0e00 is the person_id`.

curl --request PUT 'https://api.ap3api.com/v1/audience/subscribe' \
     --header 'X-Api-Key: YOUR-CUSTOM-API-KEY' \
     --header 'Content-Type: application/json' \
     --data-raw '{
      "audience_id": "61380ac92593ecf2de4fd705",
      "people": [
        {
          "person_id": "006046bbb2284e24ae0b0e00",
          "subscribed": false
        }
      ],
      "async": true
    }'

Example of subscribing and unsubscribing people to an audience for SMS

In the following example, person1@example.com is subscribed to the audience with ID 61380ac92593ecf2de4fd705 for SMS and person2@example.com is unsubscribed from that same audience for SMS. You can send subscription preferences for up to 1000 people in the same request for the same audience. Specify async: true if you want the system to return as soon as you request is accepted, rather than waiting for it to complete.

curl --request PUT 'https://api.ap3api.com/v1/audience/subscribe' \
     --header 'X-Api-Key: YOUR-CUSTOM-API-KEY' \
     --header 'Content-Type: application/json' \
     --data-raw '{
      "audience_id": "61380ac92593ecf2de4fd705",
      "people": [
        {
          "email": "person1@example.com",
          "sms_opted_in": true
        },
        {
          "email": "person2@example.com",
          "sms_opted_in": false
        }
      ],
      "async": true
    }'

If the person’s sms_permissions are false then the audience SMS subscription is ignored. You can update the sms_permissions by sending a POST /person/merge request and setting:
- "bol::sp": true
- "str::soi-ctx": "Subscribed to SMS using a custom context message"

Example of subscribing and unsubscribing people to an audience for email AND SMS

You can combine both SMS and Email preferences in the one request per person for an audience:

curl --request PUT 'https://api.ap3api.com/v1/audience/subscribe' \
     --header 'X-Api-Key: YOUR-CUSTOM-API-KEY' \
     --header 'Content-Type: application/json' \
     --data-raw '{
      "audience_id": "61380ac92593ecf2de4fd705",
      "people" :[
        {
          "email": "person1@ortto.com",
          "subscribed": true,
          "sms_opted_in": true
        },
        {
          "email": "person2@ortto.com",
          "subscribed": false,
          "sms_opted_in": false
        }
      ],
      "async": true
    }'