> 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/introduction/send-your-first-envelope.md).

# Send your first envelope

This document explains how to send, track, and download your first envelope with DocStudio API.

{% hint style="info" %}
Use the envelope UUID to retrieve the envelope, check its status, and download completed documents. For full contracts, response schemas, and status codes, use the linked API reference pages.
{% endhint %}

### Before you start

Prepare the identifiers used by the template and envelope flow. Do not create role IDs, document IDs, or field names manually. Reuse values from the template structure.

You need:

* API token
* sender and recipient mailbox UUIDs
* existing template with its UUID and version
* role IDs, document IDs, and field names from the template

Read:

* [Authentication and application tokens](/introduction/authentication-and-application-tokens.md) to get a token.
* [Working with templates and reusable IDs](/guides/templates-and-reusable-ids.md) to find template identifiers.

A basic envelope sending flow usually looks like this:

1. Get or create an API token.
2. Choose the template that will be used to create the envelope.
3. Read reusable identifiers from the template structure.
4. Find or prepare mailbox UUIDs for recipients.
5. Build the envelope XML.
6. Send the envelope.
7. Save the returned envelope UUID.
8. [Retrieve the envelope and check its status](/api-reference/check-envelope-status.md).
9. Download the completed envelope archive if needed.

### Step 1 Authenticate the request

DocStudio API requests require a token in the `Authorization` header. Use an application token for long-running integrations and a temporary authorization token only for testing or short-lived user sessions.

```
Authorization: Bearer {token}
```

{% hint style="info" %}
Use the same token format in the send request and in follow-up requests, such as retrieving the envelope by UUID.
{% endhint %}

### Step 2 Build the envelope XML

The envelope is sent as **XML** inside the JSON `data` field. The XML must reference the template UUID and template version, assign mailbox UUIDs to template roles, and send field values under the correct document IDs and field names.

```xml
<envelope templateUuid="{templateUuid}" templateVersion="{templateVersion}">
  <flow>
    <roles>
      <role id="{roleId}" mailboxUuid="{recipientMailboxUuid}" />
    </roles>
  </flow>
  <documents>
    <document id="{documentId}">
      <field name="Customer name">ACME Ltd</field>
      <field name="Contract amount">1000</field>
    </document>
  </documents>
</envelope>
```

Escape reserved XML characters before putting the XML into the JSON request body. The `data` value must be a string, so line breaks and quotes must be valid for JSON.

### Step 3 Send the envelope

Use this endpoint to create and send the envelope.

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

#### Headers

<table><thead><tr><th width="143.4443359375">Header</th><th width="176.4444580078125">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>Authorization</code></td><td>Yes</td><td>Bearer authorization token</td></tr><tr><td><code>Content-Type</code></td><td>Yes</td><td>Use <code>application/json</code></td></tr><tr><td><code>Mailbox</code></td><td>Yes</td><td>Sender mailbox UUID used as the mailbox context</td></tr></tbody></table>

#### Request body:

```json
{
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "data": "<envelope templateUuid=\"{templateUuid}\" templateVersion=\"{templateVersion}\">...</envelope>"
}
```

#### Request body fields

<table><thead><tr><th width="96.77777099609375">Field</th><th width="81.5555419921875">Type</th><th width="106.666748046875">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 added to the envelope</td></tr></tbody></table>

{% hint style="info" %}
Add `metadata` only when the envelope requires custom key-value data.
{% endhint %}

Response `201 Created`:

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

**Save the returned `uuid`**. This is the envelope UUID used for follow-up requests, including retrieving the envelope, checking status, downloading documents, and reading audit trail data.

### Step 4 Retrieve the envelope

Use the returned envelope UUID to retrieve the envelope and check its current status. Send the request in the context of the mailbox that was used to send the envelope.

<table><thead><tr><th width="293">Method</th><th>Endpoint</th></tr></thead><tbody><tr><td><code>GET</code></td><td><code>/api/v1/mailbox/{mailboxUuid}?UUID={envelopeUuid}</code></td></tr></tbody></table>

#### Headers

<table><thead><tr><th>Header</th><th>Required</th><th width="250">Description</th></tr></thead><tbody><tr><td><code>Authorization</code></td><td>Yes</td><td>Bearer authorization token</td></tr><tr><td><code>Content-Type</code></td><td>Yes</td><td>Use <code>application/json</code></td></tr><tr><td><code>mailboxUuid</code></td><td>Yes</td><td>UUID of the current mailbox</td></tr></tbody></table>

#### Path parameters

| Parameter     | Type | Required | Description                                     |
| ------------- | ---- | -------- | ----------------------------------------------- |
| `mailboxUuid` | UUID | Yes      | UUID of the mailbox used to access the envelope |

#### Query parameters

<table><thead><tr><th width="121">Parameter</th><th width="134">Type</th><th width="108">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>UUID</code></td><td>UUID</td><td>Yes</td><td>UUID of the envelope returned by the send request</td></tr></tbody></table>

#### Request example

```http
GET /api/v1/mailbox/{senderMailboxUuid}?UUID={envelopeUuid}
Authorization: Bearer {token}
Content-Type: application/json
mailboxUuid: {senderMailboxUuid}
```

The endpoint returns `200 OK` with the matching envelope data. Check the `status` field before attempting to download the completed envelope documents.

### Step 5 Download the completed archive

After the envelope is complete, download the archive if you need the final documents. Use the envelope UUID with the download endpoint.

{% hint style="warning" %}
Do not download the archive before the document files are ready. If the file is not ready yet, wait and retry according to the endpoint response and retry guidance.
{% endhint %}

### Troubleshoot the first send request

If validation fails, check the template and mailbox first, then:

* Confirm the token can access the sender mailbox.
* Confirm that template UUID, version, role IDs, document IDs, and field names match.
* Confirm that XML is valid and field values follow template rules.

### Related topics

{% columns %}
{% column %}

* [Authentication and application tokens](/introduction/authentication-and-application-tokens.md)
* [Core concepts](/introduction/core-concepts.md)
* [Working with templates and reusable IDs](/guides/templates-and-reusable-ids.md)
  {% endcolumn %}

{% column %}

* [Send Envelope](/api-reference/send-envelope.md)
* [Check Envelope Status](/api-reference/check-envelope-status.md)
* [Error handling and API error codes](/error-codes/error-handling-and-api-error-codes.md)
  {% endcolumn %}
  {% endcolumns %}