curl -X DELETE "https://api.tracklysms.com/api/v2/contacts" \
-H "X-Api-Key: trk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"phone_number": "+14155559876",
"list_number": "+18005551234"
}'
import requests
response = requests.delete(
"https://api.tracklysms.com/api/v2/contacts",
headers={
"X-Api-Key": "trk_your_api_key_here",
"Content-Type": "application/json"
},
json={
"phone_number": "+14155559876",
"list_number": "+18005551234"
}
)
data = response.json()
if data["unsubscribed"]:
print("Contact was unsubscribed successfully")
else:
print("Contact was not found on the list (or already unsubscribed)")
const response = await fetch("https://api.tracklysms.com/api/v2/contacts", {
method: "DELETE",
headers: {
"X-Api-Key": "trk_your_api_key_here",
"Content-Type": "application/json",
},
body: JSON.stringify({
phone_number: "+14155559876",
list_number: "+18005551234",
}),
});
const data = await response.json();
console.log("Unsubscribed:", data.unsubscribed);
{
"success": true,
"unsubscribed": true
}
{
"success": true,
"unsubscribed": false
}
{
"error": "phone_number is required",
"code": "missing_phone_number"
}
{
"error": "Invalid E.164 phone number format",
"code": "invalid_phone"
}
Contacts (v2)
Delete Contact
Unsubscribe a contact from a sending list by setting their subscription status to inactive.
DELETE
/
v2
/
contacts
curl -X DELETE "https://api.tracklysms.com/api/v2/contacts" \
-H "X-Api-Key: trk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"phone_number": "+14155559876",
"list_number": "+18005551234"
}'
import requests
response = requests.delete(
"https://api.tracklysms.com/api/v2/contacts",
headers={
"X-Api-Key": "trk_your_api_key_here",
"Content-Type": "application/json"
},
json={
"phone_number": "+14155559876",
"list_number": "+18005551234"
}
)
data = response.json()
if data["unsubscribed"]:
print("Contact was unsubscribed successfully")
else:
print("Contact was not found on the list (or already unsubscribed)")
const response = await fetch("https://api.tracklysms.com/api/v2/contacts", {
method: "DELETE",
headers: {
"X-Api-Key": "trk_your_api_key_here",
"Content-Type": "application/json",
},
body: JSON.stringify({
phone_number: "+14155559876",
list_number: "+18005551234",
}),
});
const data = await response.json();
console.log("Unsubscribed:", data.unsubscribed);
{
"success": true,
"unsubscribed": true
}
{
"success": true,
"unsubscribed": false
}
{
"error": "phone_number is required",
"code": "missing_phone_number"
}
{
"error": "Invalid E.164 phone number format",
"code": "invalid_phone"
}
Unsubscribes a contact from the specified sending list. This marks the contact inactive on that list with an unsubscribe reason of
api. The contact record itself is not deleted — only their subscription to the list is deactivated. This ensures historical data (send counts, click counts, revenue) is preserved for reporting.
The endpoint returns a success response even if the contact or list is not found. Check the unsubscribed field to determine whether an actual unsubscribe took place.
Body Parameters
string
required
Contact phone number in E.164 format (e.g.,
+14155559876).string
required
Sending list phone number in E.164 format (e.g.,
+18005551234). Must be a list owned by your account.Response Fields
boolean
Always
true when the request is processed without error.boolean
true if the contact was found on the list (their status is set to inactive, even if they were already unsubscribed). false only if the contact does not exist, the list does not exist, or the contact is not a member of the list.Examples
curl -X DELETE "https://api.tracklysms.com/api/v2/contacts" \
-H "X-Api-Key: trk_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"phone_number": "+14155559876",
"list_number": "+18005551234"
}'
import requests
response = requests.delete(
"https://api.tracklysms.com/api/v2/contacts",
headers={
"X-Api-Key": "trk_your_api_key_here",
"Content-Type": "application/json"
},
json={
"phone_number": "+14155559876",
"list_number": "+18005551234"
}
)
data = response.json()
if data["unsubscribed"]:
print("Contact was unsubscribed successfully")
else:
print("Contact was not found on the list (or already unsubscribed)")
const response = await fetch("https://api.tracklysms.com/api/v2/contacts", {
method: "DELETE",
headers: {
"X-Api-Key": "trk_your_api_key_here",
"Content-Type": "application/json",
},
body: JSON.stringify({
phone_number: "+14155559876",
list_number: "+18005551234",
}),
});
const data = await response.json();
console.log("Unsubscribed:", data.unsubscribed);
{
"success": true,
"unsubscribed": true
}
{
"success": true,
"unsubscribed": false
}
{
"error": "phone_number is required",
"code": "missing_phone_number"
}
{
"error": "Invalid E.164 phone number format",
"code": "invalid_phone"
}
Error Codes
| HTTP Status | Error Code | Description |
|---|---|---|
| 400 | missing_phone_number | The phone_number field was not provided in the request body. |
| 400 | missing_list_number | The list_number field was not provided in the request body. |
| 401 | invalid_credentials | Missing or invalid X-Api-Key header. |
| 403 | account_suspended | Your account is suspended. Resolve outstanding billing or contact support. |
| 400 | invalid_phone | The phone_number is not a valid E.164 phone number. |
| 400 | invalid_list_number | The list_number is not a valid E.164 phone number. |
| 500 | internal_error | An unexpected server error occurred. |
This endpoint does not delete the contact record or their historical data. It only deactivates their subscription to the specified list. To fully remove a contact’s data, use the account dashboard or contact support.
Next Steps
Importing Contacts
Manage your contact data
Create Audience
Segment your contacts