Sending messages

The Sendblue API conforms to REST API standards. Using it, you can send outbound iMessage and SMS to any enabled phone globally.

In this documentation, we will cover how to:

1. Send iMessages to a destination phone number
2. Track the status of your message using webhooks

Sending iMessages

There are two endpoints for sending messages:

• To send a message to a single phone number, use the /send-message endpoint.
• To send a message to a group, use the /send-group-message endpoint.

Request Parameters

Parameter	Type	Required	Description
number	string	Yes	E.164 formatted phone number of the recipient (e.g., “+19998887777”)
from_number	string	Yes	E.164 formatted phone number to send from (must be a number on your account)
content	string	No	The message content to send
media_url	string	No	URL to media file to send (see Sending files)
send_style	string	No	Expressive message style (see Expressive messages)
status_callback	string	No	URL to receive status updates for this message

Either content or media_url must be provided. You can send both together.

Sending files

You can send images using the media_url parameter. This URL should be a CDN link pointing to an image. The URL must end with the proper file extension. We recommend sticking to the standard PascalCase naming convention. So if your image is named “Welcome Image”, we recommend uploading it to your CDN as “WelcomeImage.png”.

Files are currently capped at 5MB.

media_url does not support signed urls, please use the media object pattern for that.

Status Callback

Sendblue will POST the endpoint you provide in status_callback whenever the status of a message changes to one of the following:

• REGISTERED
• PENDING
• DECLINED
• QUEUED
• ACCEPTED
• SENT
• DELIVERED
• ERROR

Below is an example of the POST body that is sent to the status_callback URL for a sent message:

{
  "accountEmail": "your-account-email",
  "content": "Hello world!",
  "is_outbound": true,
  "status": "SENT",
  "error_code": null,
  "error_message": null,
  "error_reason": null,
  "message_handle": "5a17319e-cbcf-443e-897e-d8b0c04b1b09",
  "date_sent": "2025-12-12T15:35:35.410Z",
  "date_updated": "2025-12-12T15:35:35.410Z",
  "from_number": "+18649820355",
  "number": "+19998887777",
  "to_number": "+19998887777",
  "was_downgraded": null,
  "plan": "dedicated",
  "media_url": "",
  "message_type": "message",
  "group_id": "",
  "participants": [],
  "send_style": "",
  "opted_out": false,
  "error_detail": null,
  "sendblue_number": null,
  "service": "iMessage",
  "group_display_name": null
}

You must send a response to our server in order to avoid receiving multiple webhook calls.

Message Status Resolution

Callback Body Field	Type	Description
accountEmail	string	Associated account email
content	string	Message content
is_outbound	boolean	True if message is sent, false if message is received
status	string	The current status of the message
error_code	int	Error code (null if no error)
error_message	string	Descriptive error message (null if no error)
error_reason	string	Additional error context (null if no error)
error_detail	string	Detailed error information (null if no error)
message_handle	string	Sendblue message handle
date_sent	string	ISO 8601 formatted date string of the date this message was created
date_updated	string	ISO 8601 formatted date string of the date this message was last updated
from_number	string	E.164 formatted phone number string of the message dispatcher
number	string	E.164 formatted phone number string of your end-user (not the Sendblue-provided phone number)
to_number	string	E.164 formatted phone number string of the message recipient
was_downgraded	boolean	True if the end user does not support iMessage, null otherwise
plan	string	Value of the Sendblue account plan
media_url	string	A CDN link to any media attached to the message
message_type	string	Type of message (e.g., “message”)
group_id	string	Group identifier (empty string for non-group messages)
participants	array	Array of participant phone numbers
send_style	string	Expressive message style if used (empty string if none)
opted_out	boolean	True if the recipient has opted out
sendblue_number	string	The Sendblue phone number used
service	string	The messaging service used (e.g., “iMessage”, “SMS”)
group_display_name	string	Display name for group chats (null for non-group messages)

Status

The status field will report the status. There are currently 8 different possible statuses:

Status	Description
REGISTERED	The message has been registered in our system
PENDING	The message has reached our servers
DECLINED	The message was rejected for some reason (see error_code and error_message for details)
QUEUED	The message has passed validation and has been queued for delivery
ACCEPTED	The message has been dequeued and is being sent
SENT	The message has been sent (terminal state for SMS, or if the receiver is not connected to the iMessage network)
DELIVERED	The message has been delivered (terminal state for iMessage or RCS)
ERROR	The message has failed to send, see the error_code field to understand why

Error Codes

Any Code besides 0 or null is a failure. Some codes are not yet documented.

Code	Description
4000	Validation Error: see error_message field
4001	Rate Limit Exceeded
4002	Blacklisted Number (e.g. 911)
5000	Internal Error
5003	Server Rate Exceeded
10001	message failed to send
10002	failed to resolve message status

Limits

Messages sent using Sendblue must be less than 18996 characters in length. If you have larger requirements we recommend breaking the message up into several, smaller messages.

Useful Information

From Number

The from_number parameter is required when sending messages. This must be a phone number that is assigned to your Sendblue account.

Sendblue focuses on message deliverability and end-user experience. Each of your users will only ever interact with your business through one Sendblue phone number. However, different clients may see different numbers for texts sent from your company. See Limits & Queues for more info.

Handle

The message handle is used so that you can query the status of each message at a later date. This is especially useful in high volume message_status=QUEUED cases or TIMEOUT cases.