Receiving messages

On free shared-line plans, a user must be verified as a contact on your account before their messages will be routed to you. Add them with sendblue add-contact +15551234567 or through the dashboard, then have them text your Sendblue number once to complete verification.

To remove this restriction, talk to us about our dedicated plans.

Receiving Messages

In order to enable receiving messages, you have to specify the webhooks that you want to use in your API dashboard.

Received Messages will be sent as a POST request to the webhook which you define. This example shows the JSON body for an inline reply:

{
  "accountEmail": "your-account-email",
  "content": "Hello!",
  "is_outbound": false,
  "status": "RECEIVED",
  "error_code": null,
  "error_message": null,
  "error_reason": null,
  "message_handle": "99DCC379-DD76-4712-BA65-11EFB33B8CD6",
  "date_sent": "2025-12-12T15:41:20.932Z",
  "date_updated": "2025-12-12T15:41:20.995Z",
  "from_number": "+19998887777",
  "number": "+19998887777",
  "to_number": "+15122164639",
  "was_downgraded": null,
  "plan": "dedicated",
  "media_url": "",
  "message_type": "message",
  "group_id": "",
  "participants": ["+19998887777", "+15122164639"],
  "send_style": "",
  "opted_out": false,
  "error_detail": null,
  "sendblue_number": "+15122164639",
  "service": "iMessage",
  "group_display_name": null,
  "reply_to": {
    "message_handle": "2F172CD8-C082-4A54-B9B3-D5B78CF4D0C3"
  },
  "thread_originator": {
    "message_handle": "2F172CD8-C082-4A54-B9B3-D5B78CF4D0C3"
  }
}

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

iMessages sent from an Apple Account email

An iMessage sender can use an Apple Account email address instead of a phone number. In that case, number and from_number contain the sender’s email address. This is an iMessage address, not an ordinary email delivery channel.

Preserve that sender identifier when processing the webhook. To reply using /api/send-message, pass it as number, just as you would a phone-number recipient. Do not substitute your Sendblue account identifier (accountEmail) or assume the sender’s phone number can be derived from the email address.

Webhook Body Parsing

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	The rule’s key when a rule declined the message (same as error_key), otherwise an error description (null if no error)
error_key	string	Stable key of the rule that declined the message (null otherwise). Branch on this field
error_reason	string	Human-readable text for display, do not parse (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	Sender’s E.164 phone number, or Apple Account email address for an email-origin iMessage
number	string	Your end-user’s sender identifier: an E.164 phone number or Apple Account email address
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 (expires after 30 days for inbound)
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 identifiers, which may include phone numbers and iMessage email addresses
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 that received the message
service	string	The messaging service used (e.g., “iMessage”, “SMS”)
group_display_name	string	Display name for group chats (null for non-group messages)
app_card	object	App Card session and state metadata when present. See App Cards.
reply_to	object	Immediate parent, with message_handle; omitted otherwise
thread_originator	object	Thread root, with message_handle and optional opaque Apple part; omitted otherwise

Inbound App Card events include extensionBundleId, teamId, balloonBundleId, url, sessionIdentifier, and a retry-stable revision inside app_card. The field is omitted from messages that are not App Cards.

See iMessage inline replies for sending replies and continuing an inbound thread.