> 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/examples/send-envelope-with-metadata.md).

# Send Envelope with Metadata

This document explains how to store and use envelope metadata through the API.

### Scenario

Send an envelope from a template and attach metadata for an external process.

### Step 1 Prepare template and metadata values

| Method | Endpoint                |
| ------ | ----------------------- |
| `POST` | `/api/v1/envelope/send` |

Prepare the template values and metadata before building the request.

You need:

{% columns %}
{% column %}

* API token
* sender mailbox UUID
* template UUID
* template version UUID
* role IDs from the template flow
  {% endcolumn %}

{% column %}

* recipient mailbox UUIDs
* document IDs from the template
* field names from the template
* metadata keys and values
  {% endcolumn %}
  {% endcolumns %}

#### Metadata rules

| Rule                  | Value                       |
| --------------------- | --------------------------- |
| Key length            | 1–32 characters             |
| Value length          | 0–128 characters            |
| Supported value types | `string`, `boolean`, `null` |

```json
{
  "customerId": "C-1024",
  "crmRecordId": "CRM-77551",
  "source": "crm",
  "priority": true,
  "externalReference": null
}
```

### Step 2 Build envelope XML

Build the envelope XML with template, role, document, and field values.

```xml
<envelope
  templateUuid="56cacd6a-ffe7-4b77-9c0c-f928d9a18cb5"
  templateVersion="ab0d11cb-ebdd-42bd-a581-ddca1bb9b585"
>
  <info>
    <subject>Sales agreement for ACME Ltd</subject>
    <message>Please review and complete the agreement.</message>
  </info>
  <flow>
    <roles>
      <role
        id="23f20eec-adad-4325-b553-1bde4be29198"
        mailboxUuid="9baec31c-e940-4894-b6d1-52033e1af66e"
      />
    </roles>
  </flow>
  <documents>
    <document id="4a61f258-fd9d-406c-b47e-81c90d4e5c47">
      <field name="customer_name">ACME Ltd</field>
      <field name="contract_amount">1250.50</field>
    </document>
  </documents>
</envelope>
```

Pass metadata in the `metadata` JSON object. Do not add it to the XML.

### Step 3 Send the request

Use these headers:

| Header          | Required | Description                |
| --------------- | -------- | -------------------------- |
| `Authorization` | Yes      | Bearer authorization token |
| `Content-Type`  | Yes      | Use `application/json`     |
| `Mailbox`       | Yes      | Sender mailbox UUID        |

Send the envelope XML in `data` and metadata in `metadata`.

```json
{
  "data": "<envelope templateUuid=\"56cacd6a-ffe7-4b77-9c0c-f928d9a18cb5\" templateVersion=\"ab0d11cb-ebdd-42bd-a581-ddca1bb9b585\">\n  <info>\n    <subject>Sales agreement for ACME Ltd</subject>\n    <message>Please review and complete the agreement.</message>\n  </info>\n  <flow>\n    <roles>\n      <role id=\"23f20eec-adad-4325-b553-1bde4be29198\" mailboxUuid=\"9baec31c-e940-4894-b6d1-52033e1af66e\" />\n    </roles>\n  </flow>\n  <documents>\n    <document id=\"4a61f258-fd9d-406c-b47e-81c90d4e5c47\">\n      <field name=\"customer_name\">ACME Ltd</field>\n      <field name=\"contract_amount\">1250.50</field>\n    </document>\n  </documents>\n</envelope>",
  "metadata": {
    "customerId": "C-1024",
    "crmRecordId": "CRM-77551",
    "source": "crm",
    "priority": true
  }
}
```

<table><thead><tr><th width="98">Field</th><th width="82">Type</th><th width="110">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>uuid</code></td><td>UUID</td><td>No</td><td>Envelope UUID when the flow already has an envelope identifier</td></tr><tr><td><code>data</code></td><td>string</td><td>Yes</td><td>Envelope XML string</td></tr><tr><td><code>metadata</code></td><td>object</td><td>No</td><td>Custom key-value metadata</td></tr></tbody></table>

### Request example

```http
POST /api/v1/envelope/send
Authorization: Bearer {token}
Content-Type: application/json
Mailbox: {senderMailboxUuid}

{
  "data": "<envelope templateUuid=\"56cacd6a-ffe7-4b77-9c0c-f928d9a18cb5\" templateVersion=\"ab0d11cb-ebdd-42bd-a581-ddca1bb9b585\">\n  <info>\n    <subject>Sales agreement for ACME Ltd</subject>\n    <message>Please review and complete the agreement.</message>\n  </info>\n  <flow>\n    <roles>\n      <role id=\"23f20eec-adad-4325-b553-1bde4be29198\" mailboxUuid=\"9baec31c-e940-4894-b6d1-52033e1af66e\" />\n    </roles>\n  </flow>\n  <documents>\n    <document id=\"4a61f258-fd9d-406c-b47e-81c90d4e5c47\">\n      <field name=\"customer_name\">ACME Ltd</field>\n      <field name=\"contract_amount\">1250.50</field>\n    </document>\n  </documents>\n</envelope>",
  "metadata": {
    "customerId": "C-1024",
    "crmRecordId": "CRM-77551",
    "source": "crm",
    "priority": true
  }
}
```

### Step 4 Save the envelope UUID

The endpoint returns `201 Created`. Save the envelope UUID.

```json
{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
```

| Field  | Type | Description           |
| ------ | ---- | --------------------- |
| `uuid` | UUID | Created envelope UUID |

### Step 5 Manage metadata

#### Update metadata

Use this endpoint to add or change metadata.

| Method | Endpoint                         |
| ------ | -------------------------------- |
| `PUT`  | `/api/v1/envelope/{id}/metadata` |

Use these headers:

| Header          | Required | Description                |
| --------------- | -------- | -------------------------- |
| `Authorization` | Yes      | Bearer authorization token |
| `Content-Type`  | Yes      | Use `application/json`     |
| `Mailbox`       | Yes      | Current mailbox UUID       |

Path parameters:

| Parameter | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id`      | UUID | Yes      | Envelope ID |

```json
{
  "crmRecordId": "CRM-77551",
  "processingStatus": "synced",
  "priority": true
}
```

The request adds new keys and overwrites existing values. The endpoint returns `200 OK`.

#### Read metadata

Read `envelope.metadata`.

```json
{
  "envelope": {
    "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "WAITING",
    "metadata": {
      "customerId": "C-1024",
      "crmRecordId": "CRM-77551",
      "source": "crm",
      "priority": true
    }
  }
}
```

#### Display metadata

Add this element to the template info section:

```xml
<metadata show="true" />
```

{% hint style="info" %}
Display metadata only when the template includes this element and metadata has a value.
{% endhint %}

### Continue processing

Use the envelope UUID to check the envelope status, process callbacks, or download the completed archive.

{% hint style="warning" %}
Keep document values in fields and external references in metadata.

* Include the `Authorization` header
* Use the sender mailbox UUID in `Mailbox`
* Confirm token access to the sender mailbox
* Send valid envelope XML in `data`
* Send a valid JSON object in `metadata`
* Use keys that are 1–32 characters long
* Use values that are 0–128 characters long
* Use supported metadata value types
* Do not include secrets or large data blocks
* Add `<metadata show="true" />` to display metadata
  {% endhint %}