---
title: Receiving messages | Sendblue Docs
description: Receiving Messages | iMessage for Business
---

On our free plans, a user must be verified as a contact on your account before their messages will be routed to you. This can be done by adding them as a contact through the dashboard.

To remove this restriction, [talk to us](https://sendblue.com/request-a-demo) 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. These messages will be delivered in the JSON of a POST body which looks like this:

```
{
  "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
}
```

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

## 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`  | 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 (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 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 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)                                    |