> 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-from-template.md).

# Send Envelope from Template

This document explains how to create, send, track, and download an envelope from a DocStudio template.

### Scenario

Send a sales agreement from a saved DocStudio template. The template already contains the document structure, recipient roles, and fields, so the API request only needs to reference the selected template version, assign real recipient mailboxes to template roles, and pass field values.

Use this example when the envelope structure is already prepared in DocStudio and the external system only starts the workflow. For example, a CRM can create an envelope from a contract template, assign the customer and manager mailboxes, prefill agreement data, and save the returned envelope UUID for tracking.

### Step 1 Prepare template values

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

Prepare all identifiers before building the request. Do not create template UUIDs, template versions, role IDs, document IDs, or field names manually; these values must come from the selected template version.

You need:

{% columns %}
{% column %}

* API token
* sender mailbox UUID
* template UUID
* template version UUID
  {% endcolumn %}

{% column %}

* role IDs from the template flow
* recipient mailbox UUIDs
* document IDs from the template
* field names from the template
  {% endcolumn %}
  {% endcolumns %}

| Template value         | Used in envelope XML                 |
| ---------------------- | ------------------------------------ |
| `template/@uuid`       | `envelope/@templateUuid`             |
| `template/@version`    | `envelope/@templateVersion`          |
| `role/@id`             | `flow > roles > role/@id`            |
| recipient mailbox UUID | `flow > roles > role/@mailboxUuid`   |
| `document/@id`         | `documents > document/@id`           |
| `field/@name`          | `documents > document > field/@name` |

#### Template fragment

This simplified template fragment shows the values that must be reused in the send request. The example has two roles and one document field; the envelope XML must use the same template UUID, template version, role IDs, document ID, and field name.

```xml
<template uuid="56cacd6a-ffe7-4b77-9c0c-f928d9a18cb5" version="ab0d11cb-ebdd-42bd-a581-ddca1bb9b585">
  <flow>
    <roles>
      <role id="23f20eec-adad-4325-b553-1bde4be29198" />
      <role id="b811f2b6-1656-42aa-9420-a9b8addb0246" />
    </roles>
  </flow>
  <documents>
    <document id="4a61f258-fd9d-406c-b47e-81c90d4e5c47">
      <field name="date field" type="date" />
    </document>
  </documents>
</template>
```

### Step 2 Build envelope XML

Build the envelope XML by referencing the template and assigning recipient mailboxes to the template roles. Field values must be placed under the correct document ID and field name from the same template version.

```xml
<envelope templateUuid="56cacd6a-ffe7-4b77-9c0c-f928d9a18cb5" templateVersion="ab0d11cb-ebdd-42bd-a581-ddca1bb9b585">
  <info>
    <subject>Sales agreement</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" />
      <role id="b811f2b6-1656-42aa-9420-a9b8addb0246" mailboxUuid="42c95245-30c1-46ef-bd5b-a9a111deec10" />
    </roles>
  </flow>
  <documents>
    <document id="4a61f258-fd9d-406c-b47e-81c90d4e5c47">
      <field name="date field">2026-07-21</field>
    </document>
  </documents>
</envelope>
```

### Step 3 Send the request

#### Headers

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

#### Request body

Send envelope XML as a string in `data`. Add [metadata](/guides/envelope-metadata.md) when the envelope needs external identifiers or other integration references.

```
{  "data": "<envelope templateUuid=\"56cacd6a-ffe7-4b77-9c0c-f928d9a18cb5\" templateVersion=\"ab0d11cb-ebdd-42bd-a581-ddca1bb9b585\"><info><subject>Sales agreement</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\"/><role id=\"b811f2b6-1656-42aa-9420-a9b8addb0246\" mailboxUuid=\"42c95245-30c1-46ef-bd5b-a9a111deec10\"/></roles></flow><documents><document id=\"4a61f258-fd9d-406c-b47e-81c90d4e5c47\"><field name=\"date field\">2026-07-21</field></document></documents></envelope>"}
```

| Field      | Type   | Required | Description                                                      |
| ---------- | ------ | -------- | ---------------------------------------------------------------- |
| `uuid`     | UUID   | No       | Envelope UUID, when the flow already has an envelope identifier. |
| `data`     | string | Yes      | Envelope XML string.                                             |
| `metadata` | object | No       | Custom key-value metadata added to the envelope.                 |

### Request example

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

```json
{
  "data": "{envelopeXml}"
}
```

### Step 4 Save the envelope UUID

The endpoint returns `201 Created` with the created envelope UUID. Save this UUID in the external system, because it is required for follow-up operations such as retrieving the envelope, checking its status, downloading documents, or matching callback events.

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

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

### Step 5 Continue processing

After the request is processed, DocStudio creates the envelope from the selected template and sends it according to the template flow. The recipient mailboxes assigned in the XML become participants in the envelope, and the provided field values are saved to the matching fields.

Use the returned UUID to check envelope status and download the envelope archive.

### Common mistakes

{% hint style="warning" %}
Use identifiers from the same template version. Set the sender mailbox in `Mailbox`, assign each template role to the correct recipient mailbox, and pass valid XML as a JSON string in `data`.
{% endhint %}