API v2 Overview

The Sendblue API v2 provides a new and improved RESTful interface for iMessage, SMS, and RCS messaging, supporting a variety of more advanced and robust features.

V2 Features

Feature	Description
Messages	Query, filter, and delete messages
Media Upload	Upload images, video, and files
Reactions	Send tapback reactions (love, like, dislike, laugh, emphasize, question)
Carousel Messaging	Send swipeable multi-image carousels (V2 lines only)
Read Receipts	Mark messages as read
Typing Indicators	Show typing status in conversations
RCS Messaging	Rich Communication Services for Android
Contacts	Full CRUD API for contact management
Contact Sharing	Configure Name & Photo Sharing profiles
Line Provisioning	Request new phone/email lines
Subaccounts	Create and manage child accounts for agency partners
TOTP (Authenticator)	Store encrypted TOTP secrets and generate 2FA codes programmatically

See also: FaceTime API (requires FaceTime line)

Base URL

https://api.sendblue.com

Authentication

All endpoints require API key headers:

sb-api-key-id: YOUR_API_KEY
sb-api-secret-key: YOUR_API_SECRET

Endpoints

Messaging

See the full guides: Sending Messages, Receiving Messages, Group Messages

Method	Endpoint	Description
POST	/api/send-message	Send a message
POST	/api/send-group-message	Send group message
POST	/api/send-carousel	Send image carousel (V2)
POST	/api/create-group	Create group chat
GET	/api/status	Get message status
GET	/api/evaluate-service	Check recipient service type

Messages

Method	Endpoint	Description
GET	/api/v2/messages	List messages with filters
GET	/api/v2/messages/:id	Get single message
DELETE	/api/message/:handle	Delete message from database

Reactions & Read Receipts

Method	Endpoint	Description
POST	/api/send-reaction	Send tapback reaction
POST	/api/mark-read	Send read receipt
POST	/api/send-typing-indicator	Send typing indicator

Media

Method	Endpoint	Description
POST	/api/upload-file	Direct file upload
POST	/api/upload-media-object	Upload from URL

Contacts

Method	Endpoint	Description
GET	/api/v2/contacts	List contacts
GET	/api/v2/contacts/count	Get contact count
GET	/api/v2/contacts/:phone	Get contact
POST	/api/v2/contacts	Create contact
POST	/api/v2/contacts/bulk	Bulk create contacts
PUT	/api/v2/contacts/:phone	Update contact
DELETE	/api/v2/contacts/:phone	Delete contact
DELETE	/api/v2/contacts	Bulk delete contacts

Webhooks

See the full guide: Webhooks

Method	Endpoint	Description
GET	/api/account/webhooks	List webhooks
POST	/api/account/webhooks	Add webhooks
PUT	/api/account/webhooks	Replace all webhooks
DELETE	/api/account/webhooks	Delete webhooks

Subaccounts

Method	Endpoint	Description
POST	/accounts/lines/request-child-account	Create child account (agency)
GET	/accounts/lines/available-area-codes	List available area codes

TOTP (Authenticator)

Method	Endpoint	Description
POST	/api/v2/totp/secrets	Register a TOTP secret
GET	/api/v2/totp/secrets	List TOTP secrets
GET	/api/v2/totp/code/:secret_id	Get current TOTP code
DELETE	/api/v2/totp/secrets/:secret_id	Delete a TOTP secret

Account

Method	Endpoint	Description
GET	/api/lines	List assigned phone numbers

Response Format

Success:

{
  "status": "OK",
  "message": "Success message",
  "data": { ... }
}

Error:

{
  "status": "ERROR",
  "error_code": "ERROR_CODE",
  "message": "Error description"
}

Service Types

Service	Description
iMessage	Apple messaging
SMS	Standard text
RCS	Rich messaging (Android)

Message Statuses

Status	Description
QUEUED	Waiting to send
PENDING	Being processed
SENT	Sent to carrier
DELIVERED	Delivered to device
ERROR	Delivery failed
DECLINED	Message rejected
RECEIVED	Inbound message
ACCEPTED	Accepted for processing
REGISTERED	Registered in system