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.

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:

• queued
• failed
• sent
• delivered
• read

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

{
  "accountEmail": "[email protected]",
  "content": "Hello world!",
  "is_outbound": true,
  "status": "DELIVERED",
  "error_code": null,
  "error_message": null,
  "message_handle": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx",
  "date_sent": "2020-09-10T06:15:05.962Z",
  "date_updated": "2020-09-10T06:15:14.115Z",
  "from_number": "+15122164639",
  "number": "+19998887777",
  "to_number": "+19998887777",
  "was_downgraded": false,
  "plan": "blue"
}

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
media_url	string	A CDN link to the image that you sent our servers
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)
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, false otherwise
plan	string	Value of the Sendblue account plan

Status

The status field will report the status. There are currently 7 different possible responses to a send-message request:

Status	Description
QUEUED	The message has reached our servers, and has passed our validation checks. It has been queued for delivery
SENT	The message has been sent
DELIVERED	The message has been sent, and we’ve received confirmation of delivery (iMessage Only)
READ	The message has been sent, and we’ve received confirmation that the end user has read the message (iMessage Only)
ERROR	The message has failed to send, see the error_code field to understaind 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

Caution

Sendblue focuses on message deliverability and end-user experience. This means that 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.

The from_number field is given as a convenience to you, in case you want to keep track of that info, or tell the client that they should expect a text from the number that you show them.

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.