API reference

Media uploads

Send images, videos, audio, and arbitrary files. Two ways to do it: pass a public URL, or upload via our presigned-URL flow for files you don't want to host yourself.

Option A: pass a public URL

If your file is already on a CDN, just pass mediaUrls:

curl -X POST 'https://api.bluereplies.com/v1/messages' \
  -H "x-api-key: $BLUEREPLIES_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "to": "+15551234567",
    "body": "Check this out:",
    "mediaUrls": ["https://cdn.example.com/photo.jpg"]
  }'

URLs must be publicly fetchable (no auth headers). We download → upload to BlueBubbles → send. Cached for 24h on our side to keep retries cheap.

Option B: presigned upload

Use this if your file isn't already hosted:

1. Request a presigned URL

POST/v1/media/upload-url

Field	Type	Description
`filename`required	string
`contentType`required	string	MIME type, e.g. `image/jpeg`, `audio/m4a`, `video/mp4`.
`size`	integer	Bytes. Used to enforce limits.

response

{
  "mediaId": "med_8x7y6w",
  "uploadUrl": "https://storage.bluereplies.com/uploads/med_8x7y6w?X-Amz-Signature=...",
  "publicUrl": "https://media.bluereplies.com/med_8x7y6w/photo.jpg",
  "expiresAt": "2026-05-25T17:38:14.221Z"
}

2. PUT the file

curl -X PUT "$UPLOAD_URL" \
  -H 'Content-Type: image/jpeg' \
  --data-binary @photo.jpg

3. Send the message

{
  "to": "+15551234567",
  "body": "Here you go",
  "mediaUrls": ["https://media.bluereplies.com/med_8x7y6w/photo.jpg"]
}

Limits & types

Max file size: 100 MB per attachment
Max attachments per message: 10
Image: jpg, png, gif, heic, webp
Video: mp4, mov (h.264/h.265 recommended)
Audio: m4a, mp3, wav, aac. Use "voiceNote": true to render as a voice memo bubble.
Documents: pdf, docx, xlsx, etc.

Receiving media (inbound)

When a recipient sends you an attachment, the message.inbound webhook payload includes attachments[] with hosted URLs. URLs are valid for 90 days; download anything you want to keep long-term.

{
  "event": "message.inbound",
  "data": {
    "id": "msg_…",
    "body": "Look at this",
    "attachments": [
      { "url": "https://media.bluereplies.com/inbound/abc.jpg",
        "contentType": "image/jpeg",
        "size": 482911,
        "filename": "IMG_4523.jpg" }
    ]
  }
}

See Webhooks for handling.