Skip to content
Project BlueDocs
Popular pages
Guides / Getting startedQuickstartGet an API key, send your first message, and confirm delivery.API reference / MessagesPOSTSend a messageSend iMessage or SMS, with media, voice memos, and message effects./send-api-messageGuides / IntegrationsWebhooksReceive message and call events at your own endpoint.Guides / Getting startedAuthenticationCreate an API key and authenticate requests with a bearer token.AI tools / AI toolsMCP server & skillConnect Claude, Codex, Cursor, and other AI tools to Project Blue.
↑ ↓ Navigate↵ Openesc Close
Dashboard
For AI agents
View as Markdown

Send a message

Send a message to a phone number via iMessage or SMS. If the recipient has iMessage, the message is delivered as an iMessage (blue bubble). Otherwise, it falls back to SMS automatically.

POST/send-api-messageBearer token
Using a trial account?
Send to a verified destination from the shared line. Set up your trial before making your first request.

Request body

messagestring
The text content of the message. Required unless mediaAttachmentUrl or audioAttachmentUrl is supplied.
phonestringRequired
Recipient phone number. Accepts many formats — we normalize to E.164 (e.g. +15551234567).
More options 11 fields
lineIdstring (UUID v4)
Optional sender line override. Use the lineId value returned from GET /get-lines. When omitted, messages are load balanced across available lines. Rejected on trial accounts — see Trial Accounts.
mediaAttachmentUrlstring
URL to an image, video, or contact card attachment.
audioAttachmentUrlstring
URL to an audio file sent as a voice memo.
enableAiVoiceMemoboolean
When true, generates an AI voice memo from the message text using text-to-speech.
shouldAutoCreateContactboolean
Defaults to true. When enabled and a supported CRM is connected (HighLevel or HubSpot), automatically creates the contact in your CRM if they don't already exist.
firstNamestring
First name to persist on the auto-created Project Blue contact for this recipient. Applies to accounts without a connected CRM (external/API source).
lastNamestring
Last name to persist on the auto-created Project Blue contact for this recipient. Applies to accounts without a connected CRM (external/API source).
emailstring
Email address to persist on the auto-created Project Blue contact for this recipient. Applies to accounts without a connected CRM (external/API source).
customFieldsobject
Arbitrary JSON metadata (e.g. order IDs, links) persisted on the auto-created contact and shown in the contact details panel in the Project Blue app. Plain object only; max 10,000 characters when JSON-serialized.
idempotencyKeystring
1 to 200 characters. Values outside those bounds are silently ignored, not rejected. When omitted, the key defaults to your user id plus the destination plus the message text, so an identical retry within the hour is collapsed rather than sent twice.
effectstring
iMessage-only send effect applied to this one message. Bubble: slam, loud, gentle, invisible-ink. Screen: confetti, balloons, hearts, lasers, fireworks, echo, spotlight, shooting-star, celebration. Invalid on SMS (400). Use sparingly.

The phone parameter is flexible — we accept formats like (555) 123-4567, 555.123.4567, +15551234567, and more. All numbers are normalized to E.164 format before sending.

When lineId is provided, we route through that line. If it is omitted, message sends continue to use default load balancing across your available lines.

iMessage-only send effects
Optional effect applies to this one message and only works on iMessage. SMS destinations return 400. Bubble effects animate the bubble: slam, loud, gentle, invisible-ink. Screen effects take over the recipient's screen: confetti, balloons, hearts, lasers, fireworks, echo, spotlight, shooting-star, celebration. Use sparingly. GET /get-effects returns the same list.
Identical sends are collapsed for an hour
With no idempotencyKey, the key defaults to your user id plus the destination plus the message text. Sending the same text to the same number twice within the hour returns 200 with deduped: true and does not send a second message. This is the usual reason a first integration looks like it succeeded but nothing arrived on the retry — change the text, or pass a distinct idempotencyKey, when a repeat is intentional.

A replay returns status: "done" when the original send finished, or status: "processing" with messageType and devicePhoneNumber still null while it is in flight. Both carry deduped: true; a first-time send never does.

API reference