Media Upload 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)

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

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 }
);