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 |
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.
Note that the |
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
}'
|
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
}'