Resubscribe Contact

curl -X POST "https://api.tracklysms.com/api/v2/contacts/resubscribe" \
  -H "X-Api-Key: trk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+14155559876",
    "list_number": "+18005551234",
    "consent_method": "web_form",
    "consent_source": "https://example.com/preferences",
    "ip_address": "203.0.113.42",
    "user_agent": "Mozilla/5.0",
    "consent_language": "I agree to receive recurring marketing text messages."
  }'

import requests

response = requests.post(
    "https://api.tracklysms.com/api/v2/contacts/resubscribe",
    headers={
        "X-Api-Key": "trk_your_api_key_here",
        "Content-Type": "application/json"
    },
    json={
        "phone_number": "+14155559876",
        "list_number": "+18005551234",
        "consent_method": "web_form",
        "consent_source": "https://example.com/preferences",
        "ip_address": "203.0.113.42",
        "user_agent": "Mozilla/5.0",
        "consent_language": "I agree to receive recurring marketing text messages."
    }
)

data = response.json()
print(f"Resubscribed: {data.get('resubscribed')}")
print(f"Carrier status: {data.get('carrier_status')}")

const response = await fetch(
  "https://api.tracklysms.com/api/v2/contacts/resubscribe",
  {
    method: "POST",
    headers: {
      "X-Api-Key": "trk_your_api_key_here",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      phone_number: "+14155559876",
      list_number: "+18005551234",
      consent_method: "web_form",
      consent_source: "https://example.com/preferences",
      ip_address: "203.0.113.42",
      user_agent: "Mozilla/5.0",
      consent_language:
        "I agree to receive recurring marketing text messages.",
    }),
  }
);

const data = await response.json();
console.log("Resubscribed:", data.resubscribed);
console.log("Carrier status:", data.carrier_status);

{
  "success": true,
  "resubscribed": true,
  "consent_status": "re_opted_in",
  "carrier_status": "cleared",
  "provider_sync": {
    "provider": "twilio",
    "opt_out_removed": true,
    "api_used": "consent_management"
  },
  "contact_id": "665a1b2c3d4e5f6a7b8c9d0e",
  "list_contact_id": "665a1b2c3d4e5f6a7b8c9d0f",
  "journeys_enrolled": 0,
  "previous_unsub_reason": "manual",
  "previous_unsub_date": "2026-01-10T09:00:00Z"
}

{
  "success": true,
  "resubscribed": true,
  "consent_status": "re_opted_in",
  "carrier_status": "pending_start_keyword",
  "carrier_instructions": "Contact must text START to +18005551234 to clear carrier block. Messages will fail until then.",
  "provider_sync": {
    "provider": "twilio",
    "opt_out_removed": true,
    "api_used": "consent_management"
  },
  "contact_id": "665a1b2c3d4e5f6a7b8c9d0e",
  "list_contact_id": "665a1b2c3d4e5f6a7b8c9d0f",
  "journeys_enrolled": 0,
  "previous_unsub_reason": "replied stop",
  "previous_unsub_date": "2026-06-20T14:30:00Z"
}

{
  "error": "consent_method is required",
  "code": "missing_consent_method"
}

{
  "error": "Contact is already active on this list",
  "code": "already_active"
}

{
  "error": "Contact opted out via STOP keyword 12 days ago. 30-day cooling-off period applies.",
  "code": "cooling_off"
}

{
  "error": "Provider consent sync failed: unknown error",
  "code": "provider_sync_failed"
}

POST

contacts

resubscribe

curl -X POST "https://api.tracklysms.com/api/v2/contacts/resubscribe" \
  -H "X-Api-Key: trk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+14155559876",
    "list_number": "+18005551234",
    "consent_method": "web_form",
    "consent_source": "https://example.com/preferences",
    "ip_address": "203.0.113.42",
    "user_agent": "Mozilla/5.0",
    "consent_language": "I agree to receive recurring marketing text messages."
  }'

import requests

response = requests.post(
    "https://api.tracklysms.com/api/v2/contacts/resubscribe",
    headers={
        "X-Api-Key": "trk_your_api_key_here",
        "Content-Type": "application/json"
    },
    json={
        "phone_number": "+14155559876",
        "list_number": "+18005551234",
        "consent_method": "web_form",
        "consent_source": "https://example.com/preferences",
        "ip_address": "203.0.113.42",
        "user_agent": "Mozilla/5.0",
        "consent_language": "I agree to receive recurring marketing text messages."
    }
)

data = response.json()
print(f"Resubscribed: {data.get('resubscribed')}")
print(f"Carrier status: {data.get('carrier_status')}")

const response = await fetch(
  "https://api.tracklysms.com/api/v2/contacts/resubscribe",
  {
    method: "POST",
    headers: {
      "X-Api-Key": "trk_your_api_key_here",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      phone_number: "+14155559876",
      list_number: "+18005551234",
      consent_method: "web_form",
      consent_source: "https://example.com/preferences",
      ip_address: "203.0.113.42",
      user_agent: "Mozilla/5.0",
      consent_language:
        "I agree to receive recurring marketing text messages.",
    }),
  }
);

const data = await response.json();
console.log("Resubscribed:", data.resubscribed);
console.log("Carrier status:", data.carrier_status);

{
  "success": true,
  "resubscribed": true,
  "consent_status": "re_opted_in",
  "carrier_status": "cleared",
  "provider_sync": {
    "provider": "twilio",
    "opt_out_removed": true,
    "api_used": "consent_management"
  },
  "contact_id": "665a1b2c3d4e5f6a7b8c9d0e",
  "list_contact_id": "665a1b2c3d4e5f6a7b8c9d0f",
  "journeys_enrolled": 0,
  "previous_unsub_reason": "manual",
  "previous_unsub_date": "2026-01-10T09:00:00Z"
}

{
  "success": true,
  "resubscribed": true,
  "consent_status": "re_opted_in",
  "carrier_status": "pending_start_keyword",
  "carrier_instructions": "Contact must text START to +18005551234 to clear carrier block. Messages will fail until then.",
  "provider_sync": {
    "provider": "twilio",
    "opt_out_removed": true,
    "api_used": "consent_management"
  },
  "contact_id": "665a1b2c3d4e5f6a7b8c9d0e",
  "list_contact_id": "665a1b2c3d4e5f6a7b8c9d0f",
  "journeys_enrolled": 0,
  "previous_unsub_reason": "replied stop",
  "previous_unsub_date": "2026-06-20T14:30:00Z"
}

{
  "error": "consent_method is required",
  "code": "missing_consent_method"
}

{
  "error": "Contact is already active on this list",
  "code": "already_active"
}

{
  "error": "Contact opted out via STOP keyword 12 days ago. 30-day cooling-off period applies.",
  "code": "cooling_off"
}

{
  "error": "Provider consent sync failed: unknown error",
  "code": "provider_sync_failed"
}

Resubscribes a contact who previously unsubscribed from a sending list. This reactivates their existing membership rather than creating a new one, and clears the opt-out across all three layers where it can be cleared automatically: your database, the SMS provider’s opt-out list, and — where applicable — the carrier network. Because resubscribing re-establishes messaging consent, consent_method is required and is validated against a fixed enum. Verbal consent is rejected for these lists (all sending lists default to marketing, and TCPA requires prior express written consent for marketing). Contacts who opted out via a STOP keyword are subject to a list-level cooling-off period and, once reactivated, return carrier_status: "pending_start_keyword" because only the consumer can clear a carrier-level block by texting START.

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 an active list owned by your account.

How the contact re-granted consent. Must be one of: web_form, sms_keyword, mobile_app, written, api_with_proof, double_opt_in. verbal is a recognized method but is rejected for these lists (see verbal_not_valid_for_marketing).

Where the consent was captured (e.g., a form URL or page identifier). Maximum 2048 characters. Stored on the membership for compliance records.

string

IP address of the contact at the time consent was re-granted. Must be a valid IPv4 or IPv6 address.

string

Browser/device user agent captured at consent time. Maximum 500 characters.

The exact consent language shown to the contact. Maximum 5000 characters.

boolean

default:"false"

When true, enroll the reactivated contact in matching Welcome Journeys. Enrollment only occurs when carrier_status resolves to cleared — a contact pending a START keyword is not enrolled because messages would fail at the carrier level.

boolean

default:"true"

When true, skips journey enrollment if the contact is already in an active workflow. Only relevant when use_journeys is true.

Response Fields

boolean

true when the contact was reactivated.

boolean

Always true on a successful response.

Consent state after reactivation. Always re_opted_in.

string

cleared when messaging can resume immediately, or pending_start_keyword when the prior opt-out was a STOP keyword and the contact must text START to clear the carrier-level block. When pending_start_keyword, carrier_instructions is also returned.

string

Present only when carrier_status is pending_start_keyword. Human-readable instruction telling the contact to text START to the list number before messages can be delivered.

object

Result of syncing the opt-out removal with the SMS provider.

Show provider_sync properties

string

The list’s provider/list type.

boolean

true when the provider removed the opt-out, null when the provider does not manage opt-out lists (no sync was attempted).

string

The provider API used to remove the opt-out (e.g., consent_management), or null when no sync was attempted.

string

Unique identifier of the Contact record.

string

Unique identifier of the ListContact record (contact-on-list membership) that was reactivated.

integer

Number of Welcome Journeys the contact was enrolled in on reactivation (0 or 1).

string

The unsubscribe reason recorded before reactivation. null if none was set.

string

ISO 8601 UTC timestamp of the prior unsubscribe. null if none was recorded.

Examples

curl -X POST "https://api.tracklysms.com/api/v2/contacts/resubscribe" \
  -H "X-Api-Key: trk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+14155559876",
    "list_number": "+18005551234",
    "consent_method": "web_form",
    "consent_source": "https://example.com/preferences",
    "ip_address": "203.0.113.42",
    "user_agent": "Mozilla/5.0",
    "consent_language": "I agree to receive recurring marketing text messages."
  }'

import requests

response = requests.post(
    "https://api.tracklysms.com/api/v2/contacts/resubscribe",
    headers={
        "X-Api-Key": "trk_your_api_key_here",
        "Content-Type": "application/json"
    },
    json={
        "phone_number": "+14155559876",
        "list_number": "+18005551234",
        "consent_method": "web_form",
        "consent_source": "https://example.com/preferences",
        "ip_address": "203.0.113.42",
        "user_agent": "Mozilla/5.0",
        "consent_language": "I agree to receive recurring marketing text messages."
    }
)

data = response.json()
print(f"Resubscribed: {data.get('resubscribed')}")
print(f"Carrier status: {data.get('carrier_status')}")

const response = await fetch(
  "https://api.tracklysms.com/api/v2/contacts/resubscribe",
  {
    method: "POST",
    headers: {
      "X-Api-Key": "trk_your_api_key_here",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      phone_number: "+14155559876",
      list_number: "+18005551234",
      consent_method: "web_form",
      consent_source: "https://example.com/preferences",
      ip_address: "203.0.113.42",
      user_agent: "Mozilla/5.0",
      consent_language:
        "I agree to receive recurring marketing text messages.",
    }),
  }
);

const data = await response.json();
console.log("Resubscribed:", data.resubscribed);
console.log("Carrier status:", data.carrier_status);

{
  "success": true,
  "resubscribed": true,
  "consent_status": "re_opted_in",
  "carrier_status": "cleared",
  "provider_sync": {
    "provider": "twilio",
    "opt_out_removed": true,
    "api_used": "consent_management"
  },
  "contact_id": "665a1b2c3d4e5f6a7b8c9d0e",
  "list_contact_id": "665a1b2c3d4e5f6a7b8c9d0f",
  "journeys_enrolled": 0,
  "previous_unsub_reason": "manual",
  "previous_unsub_date": "2026-01-10T09:00:00Z"
}

{
  "success": true,
  "resubscribed": true,
  "consent_status": "re_opted_in",
  "carrier_status": "pending_start_keyword",
  "carrier_instructions": "Contact must text START to +18005551234 to clear carrier block. Messages will fail until then.",
  "provider_sync": {
    "provider": "twilio",
    "opt_out_removed": true,
    "api_used": "consent_management"
  },
  "contact_id": "665a1b2c3d4e5f6a7b8c9d0e",
  "list_contact_id": "665a1b2c3d4e5f6a7b8c9d0f",
  "journeys_enrolled": 0,
  "previous_unsub_reason": "replied stop",
  "previous_unsub_date": "2026-06-20T14:30:00Z"
}

{
  "error": "consent_method is required",
  "code": "missing_consent_method"
}

{
  "error": "Contact is already active on this list",
  "code": "already_active"
}

{
  "error": "Contact opted out via STOP keyword 12 days ago. 30-day cooling-off period applies.",
  "code": "cooling_off"
}

{
  "error": "Provider consent sync failed: unknown error",
  "code": "provider_sync_failed"
}

Error Codes

HTTP Status	Error Code	Description
400	`missing_phone_number`	The `phone_number` field was not provided.
400	`missing_list_number`	The `list_number` field was not provided.
400	`missing_consent_method`	The `consent_method` field was not provided.
400	`invalid_consent_method`	The `consent_method` is not one of the allowed values.
400	`verbal_not_valid_for_marketing`	`consent_method=verbal` is not accepted for marketing lists. Use `web_form`, `written`, or another method.
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.
400	`list_not_found`	No active sending list with the given `list_number` exists for this account.
400	`contact_not_found`	The contact does not exist, or is not a member of the specified list.
400	`already_active`	The contact is already subscribed (active) on this list.
400	`cooling_off`	The contact opted out via a STOP keyword and the list’s cooling-off period has not elapsed.
400	`invalid_ip_address`	The `ip_address` is not a valid IPv4 or IPv6 address.
400	`field_too_long`	`consent_source`, `consent_language`, or `user_agent` exceeds its maximum length.
400	`invalid_input`	An input field contained disallowed characters.
401	`invalid_credentials`	Missing or invalid `X-Api-Key` header.
403	`account_suspended`	Your account is suspended. Resolve outstanding billing or contact support.
429	`rate_limited`	Request throttled; retry with exponential backoff after the window resets.
502	`provider_sync_failed`	The opt-out could not be removed at the SMS provider. The contact is not reactivated; retry later.
500	`internal_error`	An unexpected server error occurred.

A pending_start_keyword carrier status means the contact still has a carrier-level block from their STOP reply. No API can clear this — the contact must text START to the list number. Messages sent before then will fail at the carrier.

API Reference

V2 API Reference

Partner Accounts (v2)

Messages (v2)

Contacts (v2)

Lists (v2)

Number Requests (v2)

Business Profiles (v2)

Creatives (v2)

Audiences (v2)

Offers (v2)

Schedules (v2)

Revenue (v2)

Usage & Billing (v2)

Data Import (v2)

Links (v2)

Clicks (v2)

Webhooks (v2)

Phone Validation (v1)

API Reference (v1 - Deprecated)

Body Parameters

Response Fields

Examples

Error Codes

Next Steps

Create Contact

Delete Contact

​Body Parameters

​Response Fields

​Examples

​Error Codes

​Next Steps

Create Contact

Delete Contact

Body Parameters

Response Fields

Examples

Error Codes

Next Steps