Read Receipts API

Send read receipts to mark a conversation as read. This shows the sender that you’ve seen their message.

Send Read Receipt

Mark a conversation as read by sending a read receipt.

POST https://api.sendblue.co/api/mark-read

Request Body

Parameter	Type	Required	Description
number	string	Yes	The phone number of the conversation to mark as read (E.164 format)
from_number	string	Yes	Your Sendblue line number (E.164 format)

Example Request

curl -X POST 'https://api.sendblue.co/api/mark-read' \
  -H 'sb-api-key-id: YOUR_API_KEY' \
  -H 'sb-api-secret-key: YOUR_API_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
    "number": "+14155551234",
    "from_number": "+19175551234"
  }'

Node.js Example

const axios = require('axios');

await axios.post(
  'https://api.sendblue.co/api/mark-read',
  {
    number: '+14155551234',
    from_number: '+19175551234'
  },
  {
    headers: {
      'sb-api-key-id': 'YOUR_API_KEY',
      'sb-api-secret-key': 'YOUR_API_SECRET',
      'Content-Type': 'application/json'
    }
  }
);

Python Example

import requests

response = requests.post(
    'https://api.sendblue.co/api/mark-read',
    json={
        'number': '+14155551234',
        'from_number': '+19175551234'
    },
    headers={
        'sb-api-key-id': 'YOUR_API_KEY',
        'sb-api-secret-key': 'YOUR_API_SECRET'
    }
)

Success Response (200)

{
  "status": "OK",
  "message": "Mark read request sent",
  "number": "+14155551234"
}

---

Error Responses

Missing Number (400)

{
  "status": "ERROR",
  "message": "You must specify a `number` in the request body."
}

Missing from_number (400)

{
  "status": "ERROR",
  "message": "You must specify a valid `from_number` in the request body."
}

Line Not Found (404)

{
  "status": "ERROR",
  "message": "The from_number is not registered"
}

---

Notes

1. iMessage Only: Read receipts only work for iMessage conversations, not SMS.

2. No Delivery Confirmation: Read receipts are sent on a “best effort” basis. There’s no confirmation that the recipient’s device received the read status.

3. Recent Messages: Read receipts work best when sent shortly after receiving a message. Very old conversations may not show the read status.