# Update

`POST` `https://api.pushwoosh.com/messaging/v2/update`

Replaces a previously created message, identified by its `message_code`, with a new definition. The replacement is a **full replace, not a patch**: the new definition is applied exactly as sent, and the `message_code` does not change.

Update is available only while the message is still **pending** — scheduled for a future send and not yet picked up for processing or delivery.

<Aside type="caution" title="Important">

- The `request` field is a complete [`Notify`](/developer/api-reference/messaging-api-v2/notify/) definition. Fields you omit are **not** carried over from the original message — they are reset. Send the full message you want, not just the changed parts.

- If the message is already processing, has been delivered, was canceled, or was deleted, the API returns `400`. This call is not idempotent. Check the message status before you update.
</Aside>

To check whether a message is still in an updatable state, see [Checking message status](#checking-message-status).


## Request

Authenticate with your [Server API token](/developer/api-reference/api-access-token/#server-api-token) in the `Authorization: Token <API_TOKEN>` header.

| Field | Type | Required | Description |
|---|---|---|---|
| `message_code` | string | Yes | [Message code](/developer/api-reference/api-identifiers/#message-code) of the message to update, as returned by [`Notify`](/developer/api-reference/messaging-api-v2/notify/) in `result.message_code`. |
| `request` | object | Yes | The full new definition of the message. Same shape as the [`Notify`](/developer/api-reference/messaging-api-v2/notify/) request body — a `segment` or `transactional` object. Validated exactly like `Notify`. |

### Example request

Reschedule a segment message and change its content:

```bash
curl -X POST https://api.pushwoosh.com/messaging/v2/update \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message_code": "XXXX-XXXXXXXX-XXXXXXXX",
    "request": {
      "segment": {
        "application": "XXXXX-XXXXX",
        "platforms": ["IOS", "ANDROID"],
        "code": "active_users",
        "payload": {
          "content": {
            "localized_content": {
              "en": {
                "ios":     { "body": "Updated message" },
                "android": { "body": "Updated message" }
              }
            }
          }
        },
        "schedule": { "at": "2026-05-02T12:00:00Z" },
        "message_type": "MESSAGE_TYPE_MARKETING"
      }
    }
  }'
```

## Response

On success, returns HTTP 200 with the result of the updated message. The `message_code` is unchanged.

```json
{
  "result": {
    "message_code": "XXXX-XXXXXXXX-XXXXXXXX",
    "unknown_identifiers": []
  }
}
```

- `message_code` (string): the same code that was passed in the request.
- `unknown_identifiers` (array of string): identifiers in the new definition that were not found, when applicable (see [`Notify`](/developer/api-reference/messaging-api-v2/notify/)).

## Errors

Errors use the standard gRPC-Gateway error envelope: `{ "code": ..., "message": ..., "details": [...] }`.

| HTTP status | Condition |
|---|---|
| `400` | `message_code` is missing. |
| `400` | The new `request` definition is missing or invalid (it is validated exactly like [`Notify`](/developer/api-reference/messaging-api-v2/notify/)). |
| `400` | The message is not in an updatable state (it is no longer `pending`). |
| `403` | The message belongs to another account. |
| `404` | No message exists for the given `message_code`. |
| `500` | An internal error occurred while loading the message or applying the update. Retry the request. |


**Example**

Updating a message that no longer exists returns HTTP `404`:

```json
{
  "code": 5,
  "message": "message not found",
  "details": []
}
```

## Checking message status

Before updating, you can verify whether a message is still in an updatable state. Besides reading the **Status** column in the messages table in the Control Panel ([**Campaigns → One-time messages**](/product/statistics-and-analytics/message-history/)), you can query the status programmatically with [`messages:list`](/developer/api-reference/statistics-api/message-statistics-api/#messageslist):

- Pass the `message_code` in the `filters.messages_codes` array (alongside the required `filters.application`).
- Read the `status` field of the matching entry in `items[]`.

<Aside type="note">
`messages:list` is part of the Statistics API and uses a different auth header than this endpoint: `Authorization: Api <Server Key>`.
</Aside>

## Related

<CardGrid>
  <LinkCard title="Notify" href="/developer/api-reference/messaging-api-v2/notify/" />
  <LinkCard title="Cancel" href="/developer/api-reference/messaging-api-v2/cancel/" />
  <LinkCard title="Message statistics" href="/developer/api-reference/statistics-api/message-statistics-api/#messageslist" />
  <LinkCard title="Messaging API v2 overview" href="/developer/api-reference/messaging-api-v2/" />
  <LinkCard title="Migration from v1" href="/developer/api-reference/messaging-api-v2/migration-from-v1/" />
</CardGrid>