---
title: API v2 Overview | Sendblue Docs
description: RESTful API for messaging, contacts, and account management
---

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](/api-v2/messages/index.md)                   | Query, filter, and delete messages                                       |
| [Media Upload](/api-v2/media/index.md)                  | Upload images, video, and files                                          |
| [Reactions](/api-v2/reactions/index.md)                 | Send tapback reactions (love, like, dislike, laugh, emphasize, question) |
| [Carousel Messaging](/api-v2/carousel/index.md)         | Send swipeable multi-image carousels (V2 lines only)                     |
| [Read Receipts](/api-v2/read-receipts/index.md)         | Mark messages as read                                                    |
| [Typing Indicators](/api-v2/typing-indicators/index.md) | Show typing status in conversations                                      |
| [RCS Messaging](/api-v2/rcs/index.md)                   | Rich Communication Services for Android                                  |
| [Contacts](/api-v2/contacts/index.md)                   | Full CRUD API for contact management                                     |
| [Contact Sharing](/api-v2/contact-sharing/index.md)     | Configure Name & Photo Sharing profiles                                  |
| [Line Provisioning](/api-v2/line-provisioning/index.md) | Request new phone/email lines                                            |

See also: [FaceTime API](/calling/facetime/index.md) (requires FaceTime line)

## Base URL

```
https://api.sendblue.co
```

## Authentication

All endpoints require API key headers:

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

## Endpoints

### Messaging

| 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

| 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      |

### 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    |