Contacts: Lists
Set List Subscription
Unsubscribe up to 500 contacts from one list, or subscribe them back, without touching their other lists or global status.
https://g.sendcorex.com/v1/contactscommand: set_list_subscriptionNeeds the contact:update scope on your API key.
Contacts that are not members of the list are left as they are and come back with changed: false. Use Add To Lists to make them members first.
Arguments
emailsstring[]optionalUp to 500 emails. Case and surrounding spaces are ignored, and repeated emails count once.
emailstringoptionalA single email. Use this or
emails.list_idstringrequiredThe list.
e.g.
"newsletter"subscribedbooleanrequiredfalseto unsubscribe from this list,trueto subscribe again.return_contactsbooleanoptionalAdd the whole contact after the change to each item.
Quick start
import axios from 'axios';
const response = await axios.post(
'https://g.sendcorex.com/v1/contacts',
{
commands: [
{
command: "set_list_subscription",
args: {
emails: [
"bob@gmail.com"
],
list_id: "newsletter",
subscribed: false
}
}
]
},
{ headers: { Authorization: process.env.SENDCOREX_API_KEY } },
);
const [result] = response.data.results;
if (result.type !== 'SUCCESS') throw new Error(`${result.code}: ${result.message}`);
console.log(result.data);Response
{
"type": "SUCCESS",
"results": [
{
"command": "set_list_subscription",
"id": "0",
"type": "SUCCESS",
"took_ms": 14,
"data": {
"items": [
{
"id": "bob@gmail.com",
"ok": true,
"data": {
"changed": true
}
}
],
"ok_count": 1,
"failed_count": 0
}
}
]
}Response fields
items[].idThe email you sent, as you sent it.
items[].oktruewhen this email worked. Whenfalse, the item hascodeandmessage.items[].data.changedfalsemeans the contact was already like this, so nothing was written.items[].data.contactThe whole contact after the change. Only with
return_contacts: true.ok_count / failed_countHow many emails worked and how many failed.
List subscription or global status?
Set List SubscriptionThe person still wants your other lists. They stay a member here, marked unsubscribed, and stop being sendable in this list only.
Set StatusThe person wants no email at all, or the address bounced. Sendable becomes
falsein every list.
Errors
HTTP-level errors return type, code and message. Errors marked CMD come back inside the command result, with HTTP 200.
- 401
INVALID_API_KEYThe API key does not exist, was revoked or was disabled in the dashboard.
- 429
RATE_LIMITEDMore than 15 requests/s or 15 in flight for the same IP + API key. Wait the number of seconds in Retry-After.
- CMD
MISSING_SCOPEThe API key does not have the scope this command needs. The other commands in the request still run.
- CMD
INVALID_ARGSA required argument is missing or invalid: email, field value, enum option, where key, list id…
- CMD
NOT_FOUNDThe contact, list, field or segment does not exist.
- CMD
INTERNALServer error. The detail is only written to the server log.