Skip to main content
Every contact has a messaging status that controls whether you can send them messages. You can retrieve the current status for a contact and update it programmatically. This is useful for syncing opt-out lists, enforcing compliance, or blocking contacts who should not receive any further messages.

​
Status values

ValueDescription
activeThe contact is active and can receive messages.
blockedThe contact is blocked. No messages will be delivered.
unblockedRemoves a previous block, restoring the contact to active.
subscribedMarks the contact as subscribed to messages.
unsubscribedMarks the contact as opted out. Equivalent to setting is_opted_out: true.

​
The ContactStatusResponse object

​
id
integer
Integer ID of the contact.
​
phone
string
Phone number of the contact in E.164 format without the leading +.
​
unsubscribed
boolean
true if the contact has opted out of messages.
​
blocked
boolean
true if the contact is blocked from receiving messages.

​
POST /v1/contact/status

Returns the current messaging status for a contact.

​
Request body

​
id
integer
The integer ID of the contact.
​
phone
string
The contact’s phone number in E.164 format without the leading +.
Provide either id or phone. At least one is required.

​
Response

Returns a ContactStatusResponse object.

​
Example

curl -X POST https://api.heymarket.com/v1/contact/status \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone": "15105553344"}'

{
  "id": 98765,
  "phone": "15105553344",
  "unsubscribed": false,
  "blocked": false
}

​
POST /v1/contact/set_status

Updates the messaging status of a contact.

​
Request body

​
id
integer
The integer ID of the contact.
​
phone
string
The contact’s phone number in E.164 format without the leading +.
​
status
string
required
The new status to apply. One of: active, blocked, unblocked, subscribed, unsubscribed.
Provide either id or phone to identify the contact. At least one is required.

​
Response

Returns a success string on completion.

​
Examples

curl -X POST https://api.heymarket.com/v1/contact/set_status \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "15105553344",
    "status": "blocked"
  }'
The is_opted_out field on the Contact object reflects whether the contact has been unsubscribed. Setting status to unsubscribed sets is_opted_out to true; setting it to subscribed sets it back to false.
Setting status to blocked prevents all future messages to that contact, regardless of campaign or inbox settings. Use unblocked to reverse a block.