---
title: Carousel Messaging API | Sendblue Docs
description: Send swipeable multi-image carousels via the Sendblue API
---

Send multiple images as a swipeable carousel in iMessage. Carousel messaging is only available on V2 (Mac Mini) lines.

## Send a Carousel

```
POST https://api.sendblue.co/api/send-carousel
```

### Request Body

| Parameter         | Type      | Required | Description                                                                                |
| ----------------- | --------- | -------- | ------------------------------------------------------------------------------------------ |
| `number`          | string    | Yes      | Recipient phone number (E.164). Aliases: `recipient`, `to`                                 |
| `from_number`     | string    | Yes      | Your V2 (Mac Mini) Sendblue line (E.164). Aliases: `fromNumber`, `from`, `sendblue_number` |
| `media_urls`      | string\[] | Yes      | Array of 2–20 HTTPS image URLs. Alias: `mediaURLs`                                         |
| `status_callback` | string    | No       | Webhook URL for delivery status. Alias: `statusCallback`                                   |
| `send_style`      | string    | No       | iMessage send effect. Alias: `sendStyle`                                                   |
| `metadata`        | object    | No       | Custom metadata returned in webhooks                                                       |

### Example Request

Terminal window

```
curl -X POST 'https://api.sendblue.co/api/send-carousel' \
  -H 'sb-api-key-id: YOUR_API_KEY' \
  -H 'sb-api-secret-key: YOUR_API_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
    "number": "+19175551234",
    "from_number": "+14155559876",
    "media_urls": [
      "https://example.com/image1.jpg",
      "https://example.com/image2.jpg",
      "https://example.com/image3.jpg"
    ]
  }'
```

### Node.js Example

```
const axios = require('axios');


await axios.post(
  'https://api.sendblue.co/api/send-carousel',
  {
    number: '+19175551234',
    from_number: '+14155559876',
    media_urls: [
      'https://example.com/image1.jpg',
      'https://example.com/image2.jpg',
      'https://example.com/image3.jpg'
    ]
  },
  {
    headers: {
      'sb-api-key-id': 'YOUR_API_KEY',
      'sb-api-secret-key': 'YOUR_API_SECRET',
      'Content-Type': 'application/json'
    }
  }
);
```

### Success Response (202)

```
{
  "status": "QUEUED",
  "accountEmail": "you@example.com",
  "message_handle": "abc123-def456",
  "number": "+19175551234",
  "from_number": "+14155559876",
  "media_url": "https://example.com/image1.jpg",
  "is_outbound": true,
  "message_type": "carousel"
}
```

---

## Error Responses

### Missing or invalid media\_urls (400)

```
{
  "status": "ERROR",
  "message": "'media_urls' is required — an array of 2-20 HTTPS URLs"
}
```

### Too few media URLs (400)

```
{
  "status": "ERROR",
  "message": "Carousel requires at least 2 media URLs. For single media, use /send-message with media_url."
}
```

### Too many media URLs (400)

```
{
  "status": "ERROR",
  "message": "'media_urls' must contain at most 20 items"
}
```

### Non-HTTPS URL (400)

```
{
  "status": "ERROR",
  "message": "media_urls[0] must be an HTTPS URL"
}
```

### Missing from\_number (400)

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

### V2 line required (400)

```
{
  "status": "ERROR",
  "message": "Carousel messaging is only available on V2 lines"
}
```

### Cannot send to self (400)

```
{
  "status": "ERROR",
  "message": "Cannot send messages to self"
}
```

### Line not found (404)

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

## Notes

1. **V2 Only**: Carousel messaging requires a V2 (Mac Mini) Sendblue line. It is not available on V1 lines.

2. **2–20 Images**: You must provide between 2 and 20 HTTPS image URLs. For sending a single image, use [`/api/send-message`](/api-v2/messages/index.md) with the `media_url` parameter.

3. **HTTPS Required**: All media URLs must use HTTPS.