---
title: Media Upload API | Sendblue Docs
description: Upload files and media for sending via iMessage with the Sendblue API
---

Upload files to Sendblue’s CDN for use in iMessage. Uploaded files can be sent as attachments using the `media_url` parameter in the send message endpoint.

## Direct File Upload

Upload a file directly via multipart form data.

```
POST https://api.sendblue.co/api/upload-file
```

### Request

- **Content-Type**: `multipart/form-data`
- **Body**: File as form field named `file`

### Limits

- Maximum file size: **100 MB**

### Example Request (cURL)

Terminal window

```
curl -X POST 'https://api.sendblue.co/api/upload-file' \
  -H 'sb-api-key-id: YOUR_API_KEY' \
  -H 'sb-api-secret-key: YOUR_API_SECRET' \
  -F 'file=@/path/to/document.pdf'
```

### Node.js Example

```
const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');


const form = new FormData();
form.append('file', fs.createReadStream('./document.pdf'));


const response = await axios.post(
  'https://api.sendblue.co/api/upload-file',
  form,
  {
    headers: {
      ...form.getHeaders(),
      'sb-api-key-id': 'YOUR_API_KEY',
      'sb-api-secret-key': 'YOUR_API_SECRET'
    }
  }
);


console.log(response.data.media_url);
// Use this URL in send-message endpoint
```

### Python Example

```
import requests


url = 'https://api.sendblue.co/api/upload-file'
files = {'file': open('document.pdf', 'rb')}
headers = {
    'sb-api-key-id': 'YOUR_API_KEY',
    'sb-api-secret-key': 'YOUR_API_SECRET'
}


response = requests.post(url, files=files, headers=headers)
print(response.json()['media_url'])
```

### Success Response (201)

```
{
  "status": "OK",
  "message": "File uploaded successfully",
  "media_url": "https://storage.googleapis.com/inbound-file-store/abc123_document.pdf",
  "mediaObjectId": "abc123_document.pdf"
}
```

---

## Upload from URL

Download media from a URL and re-host it on Sendblue’s CDN. Useful for ensuring media persists and is accessible by iMessage.

```
POST https://api.sendblue.co/api/upload-media-object
```

### Request Body

| Parameter   | Type   | Required | Description                     |
| ----------- | ------ | -------- | ------------------------------- |
| `media_url` | string | Yes      | The source URL to download from |

### Example Request

Terminal window

```
curl -X POST 'https://api.sendblue.co/api/upload-media-object' \
  -H 'sb-api-key-id: YOUR_API_KEY' \
  -H 'sb-api-secret-key: YOUR_API_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
    "media_url": "https://example.com/image.jpg"
  }'
```

### Node.js Example

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


const response = await axios.post(
  'https://api.sendblue.co/api/upload-media-object',
  {
    media_url: 'https://example.com/image.jpg'
  },
  {
    headers: {
      'sb-api-key-id': 'YOUR_API_KEY',
      'sb-api-secret-key': 'YOUR_API_SECRET',
      'Content-Type': 'application/json'
    }
  }
);


console.log(response.data.mediaObjectId);
```

### Success Response (201)

```
{
  "status": "OK",
  "message": "File uploaded successfully",
  "mediaObjectId": "xyz789.jpg"
}
```

---

## Error Responses

### No File Uploaded (400)

```
{
  "status": "ERROR",
  "message": "No file uploaded"
}
```

### No URL Provided (400)

```
{
  "status": "ERROR",
  "message": "No media url specified"
}
```

### Invalid URL (400)

```
{
  "status": "ERROR",
  "message": "Invalid media url"
}
```

### Upload Failed (500)

```
{
  "status": "ERROR",
  "message": "Failed to upload file to storage"
}
```

---

## Supported File Types

All file types are supported. Common types include:

| Type      | Extensions                |
| --------- | ------------------------- |
| Images    | JPG, PNG, GIF, HEIC, WebP |
| Videos    | MP4, MOV, M4V             |
| Audio     | M4A, MP3, AAC, CAF        |
| Documents | PDF, VCF (contact cards)  |

---

## Usage with Send Message

After uploading, use the returned `media_url` in your send message request:

```
// 1. Upload the file
const uploadResponse = await axios.post(
  'https://api.sendblue.co/api/upload-file',
  formData,
  { headers: { ...form.getHeaders(), ...authHeaders } }
);


// 2. Send message with the uploaded media
await axios.post(
  'https://api.sendblue.co/api/send-message',
  {
    number: '+14155551234',
    from_number: '+19175551234',
    content: 'Check out this document!',
    media_url: uploadResponse.data.media_url
  },
  { headers: authHeaders }
);
```