Contacts: Tags, status & fields
Set Status
Change the global status of up to 500 contacts: unsubscribe, block or resubscribe them across every list at once.
https://g.sendcorex.com/v1/contactscommand: set_statusNeeds the contact:update scope on your API key.
Status is global. A contact that is not subscribed is not sendable in any list, even if it is still subscribed there. To leave a single list, use Set List Subscription.
Arguments
emailsstring[]optionalUp to 500 emails. Case and surrounding spaces are ignored, and repeated emails count once.
emailstringoptionalA single email. Use this or
emails.statusstringrequiredsubscribed,unsubscribed,bounced,complainedorblocked.e.g.
"unsubscribed"reasonstringoptionalWhy the status changed. Stored as
status_reason.e.g.
"asked by email"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_status",
args: {
emails: [
"bob@gmail.com"
],
status: "unsubscribed",
reason: "asked by email"
}
}
]
},
{ 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_status",
"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.
Statuses
subscribedCan receive email from the lists it is subscribed to.
unsubscribedAsked to stop receiving email.
bouncedThe address does not accept email.
complainedMarked one of your emails as spam.
blockedBlocked by you. Use it for addresses you never want to email.
Setting subscribed again on someone who unsubscribed or complained should only happen when they asked for it.
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.