---
title: "Send a single text or attachment message"
method: POST
path: "/v1/api/messages"
tags: ["Messages"]
---

# Send a single text or attachment message

`POST /v1/api/messages`

Queues an outbound iMessage/SMS to the specified phone number.

Supports optional media attachments via public URLs, and arbitrary metadata for correlation.

For safe retries, provide an `Idempotency-Key` header. If the same key is used twice, the original message will be returned with 200; otherwise a new message is queued with 202.

## Headers

- `Idempotency-Key` string

## Request body

- SendMessageRequest
  - `to` string, required — Recipient phone number in E.164 format (e.g., +15551234567)
  - `text` string — Text body of the message.
  - `attachments` string[] — Array of publicly accessible URLs to media attachments.
  - `metadata` object — Arbitrary key/value pairs to associate with the message.

## Response `200`

Message already exists (idempotency key match).

- QueuedResponse
  - `message_id` string
  - `status` string

## Other responses

- `202` — Message accepted and queued for delivery.
- `400` — Invalid request parameters.
- `401` — Invalid or missing API key.
- `402` — Trial limit reached or payment required.
- `403` — Action not allowed for this API key.
- `409` — Conflict with current state (e.g., cannot cancel a message that already sent).
- `503` — No active devices available.

---

[API](https://skmtc.dev/blooio/apis/blooio-messaging-api-v3.md) · [All operations](https://skmtc.dev/blooio/apis/blooio-messaging-api-v3/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/blooio/blooio-messaging-api-v3/revisions/2d1e4d94ef5b/schema)