Read Receipts API

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

Note: Read receipts must be enabled by the Sendblue engineering team for your account. Contact [email protected] to request activation.

Send Read Receipt

Mark a conversation as read by sending a read receipt.

POST https://api.sendblue.com/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.com/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.com/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.com/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 & RCS Only: Read receipts work for iMessage and RCS 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.

---

Auto Mark-Read

Plan availability: Auto mark-read is available on the Free API plan and the AI Agent plan. You can enable it from the account settings page in your dashboard, or via the API endpoint below.

When auto mark-read is enabled, Sendblue automatically sends a read receipt on every inbound 1:1 iMessage your line receives. Useful for AI-agent and async-workflow setups where you want the sender to see their message has landed even while your backend is processing the response.

What auto-fires

The auto-trigger only runs when all of these are true:

• The inbound is an iMessage (not SMS or RCS — those don’t carry read receipts)
• It’s a 1:1 conversation, not a group chat
• It’s the first part of the inbound (multi-attachment messages don’t fire twice)

If any of those don’t hold, no auto read receipt is sent and the inbound flows through normally.

Enable / Disable

POST https://api.sendblue.com/accounts/settings/auto-mark-read

Request Body

Parameter	Type	Required	Description
auto_mark_read	boolean	Yes	true to enable, false to disable

Example Request

curl -X POST 'https://api.sendblue.com/accounts/settings/auto-mark-read' \
  -H 'sb-api-key-id: YOUR_API_KEY' \
  -H 'sb-api-secret-key: YOUR_API_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
    "auto_mark_read": true
  }'

Node.js Example

const axios = require('axios');

await axios.post(
  'https://api.sendblue.com/accounts/settings/auto-mark-read',
  { auto_mark_read: true },
  {
    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.com/accounts/settings/auto-mark-read',
    json={'auto_mark_read': True},
    headers={
        'sb-api-key-id': 'YOUR_API_KEY',
        'sb-api-secret-key': 'YOUR_API_SECRET'
    }
)

Success Response (200)

{
  "status": "OK",
  "auto_mark_read": true
}

Error Responses

Missing or non-boolean value (400)

{
  "status": "ERROR",
  "message": "auto_mark_read must be a boolean"
}

Notes

1. Setting takes effect on the next inbound. Cached account data invalidates immediately after the toggle write.
2. Auto and manual coexist. Toggling auto on doesn’t disable the manual POST /api/mark-read endpoint — you can still send explicit receipts when you want.
3. Same delivery semantics as the manual endpoint: best-effort, iMessage/RCS-only, no recipient confirmation.