> For the complete documentation index, see [llms.txt](https://developers.docstudio.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.docstudio.com/api-reference/check-envelope-status.md).

# Check Envelope Status

This document contains details for the /api/v1/envelope/{envelopeUuid} endpoint, including headers, parameters, response fields, and status codes.

Use this endpoint when you already know the envelope UUID and need to retrieve its latest status and details. If you need to find envelopes or filter a list by status and other criteria, use `POST /api/v1/envelope/search` instead. The current status of the retrieved envelope is returned in `envelope.status`.

### Endpoint

| Method | Endpoint                          |
| ------ | --------------------------------- |
| `GET`  | `/api/v1/envelope/{envelopeUuid}` |

### Headers

| Header          | Required | Description                                             |
| --------------- | -------- | ------------------------------------------------------- |
| `Authorization` | Yes      | Bearer authorization token                              |
| `Mailbox`       | Yes      | UUID of the mailbox used as the current mailbox context |

### Path parameters

| Parameter      | Type | Required | Description                      |
| -------------- | ---- | -------- | -------------------------------- |
| `envelopeUuid` | UUID | Yes      | UUID of the envelope to retrieve |

### Request example

```http
GET /api/v1/envelope/89499ba2-287d-404c-87b0-342dc5b01b6a
Authorization: Bearer {token}
Mailbox: 9baec31c-e940-4894-b6d1-52033e1af66e
```

### Response

The endpoint returns `200 OK` with envelope, template, and scenario details.

```json
{
  "envelope": {
    "uuid": "89499ba2-287d-404c-87b0-342dc5b01b6a",
    "createdAt": "2026-08-27T13:02:46.796Z",
    "receivedAt": "2026-08-27T13:02:46.796Z",
    "sentAt": "2026-08-27T13:02:46.796Z",
    "status": "COMPLETED",
    "sender": {
      "mailboxUuid": "fdfde267-6558-40a9-93fd-e59529baef36",
      "mailboxName": "Sender mailbox",
      "accountUuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "accountName": "Sender account"
    },
    "deleted": false,
    "archived": false,
    "metadata": {
      "customerId": "ACME-1001"
    }
  },
  "template": {
    "uuid": "56cacd6a-ffe7-4b77-9c0c-f928d9a18cb5",
    "name": "Sales agreement",
    "version": "143a2a4b-325e-4c05-a4c1-52f44e21b745"
  },
  "scenario": null
}
```

#### Response fields

| Field      | Type             | Description                     |
| ---------- | ---------------- | ------------------------------- |
| `envelope` | object           | Envelope details                |
| `template` | object           | Template details                |
| `scenario` | object or `null` | Scenario details when available |

#### Envelope fields

| Field        | Type     | Description                        |
| ------------ | -------- | ---------------------------------- |
| `uuid`       | UUID     | Envelope UUID                      |
| `createdAt`  | datetime | Envelope creation time             |
| `receivedAt` | datetime | Envelope receipt time              |
| `sentAt`     | datetime | Envelope send time                 |
| `status`     | string   | Current envelope status            |
| `sender`     | object   | Sender mailbox and account details |
| `deleted`    | boolean  | Whether the envelope is deleted    |
| `archived`   | boolean  | Whether the envelope is archived   |
| `metadata`   | object   | Custom envelope metadata           |

#### Sender fields

| Field         | Type   | Description         |
| ------------- | ------ | ------------------- |
| `mailboxUuid` | UUID   | Sender mailbox UUID |
| `mailboxName` | string | Sender mailbox name |
| `accountUuid` | UUID   | Sender account UUID |
| `accountName` | string | Sender account name |

#### Template fields

| Field     | Type   | Description           |
| --------- | ------ | --------------------- |
| `uuid`    | UUID   | Template UUID         |
| `name`    | string | Template name         |
| `version` | UUID   | Template version UUID |

### Status codes

| Code  | Description                                      |
| ----- | ------------------------------------------------ |
| `200` | Envelope retrieved successfully                  |
| `401` | Missing, invalid, or expired authorization token |
| `403` | No access to the specified mailbox               |
| `404` | Envelope or mailbox not found                    |

### Related topics

* [Authorization](/api-reference/authorization.md)
* [Send Envelope](/api-reference/send-envelope.md)
* [Error handling and API error codes](/error-codes/error-handling-and-api-error-codes.md)