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

# Send Envelope

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

### Endpoint

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

### Headers

| Header          | Required | Description                |
| --------------- | -------- | -------------------------- |
| `Authorization` | Yes      | Bearer authorization token |
| `Content-Type`  | Yes      | `application/json`         |
| `Mailbox`       | Yes      | UUID of the sender mailbox |

Use a token with access to the sender mailbox.

### Request

| Field      | Type   | Required | Description                              |
| ---------- | ------ | -------- | ---------------------------------------- |
| `uuid`     | UUID   | No       | Predefined envelope UUID                 |
| `data`     | string | Yes      | Envelope XML serialized as a JSON string |
| `metadata` | object | No       | Custom envelope metadata                 |

### Envelope XML

Use identifiers from the same template version.

| Envelope value              | Source                                              |
| --------------------------- | --------------------------------------------------- |
| `envelope/@templateUuid`    | Template UUID                                       |
| `envelope/@templateVersion` | Template version UUID                               |
| `role/@id`                  | Role ID from the template flow                      |
| `role/@mailboxUuid`         | Recipient mailbox UUID                              |
| `document/@id`              | Document ID from the selected template version      |
| `field/@name`               | Exact field name from the selected template version |

Example envelope XML:

```xml
<envelope
  templateUuid="{templateUuid}"
  templateVersion="{templateVersion}"
>
  <info>
    <subject>Sales agreement</subject>
    <message>Please review and complete the agreement.</message>
  </info>

  <flow>
    <roles>
      <role
        id="{roleId}"
        mailboxUuid="{recipientMailboxUuid}"
      />
    </roles>
  </flow>

  <documents>
    <document id="{documentId}">
      <field name="Customer name">ACME Ltd</field>
      <field name="Contract amount">1250.50</field>
    </document>
  </documents>
</envelope>
```

### Request example

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

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

### Optional request fields

#### `uuid`

Set `uuid` when the integration assigns the envelope UUID.

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

#### `metadata`

Set `metadata` to store custom envelope data.

```json
{
  "data": "{envelopeXml}",
  "metadata": {
    "customerId": "C-1024",
    "crmRecordId": "CRM-77551",
    "priority": true
  }
}
```

### Response

The endpoint returns `201 Created` with the created envelope UUID.

```json
{
  "uuid": "89499ba2-287d-404c-87b0-342dc5b01b6a"
}
```

| Field  | Type | Description                  |
| ------ | ---- | ---------------------------- |
| `uuid` | UUID | UUID of the created envelope |

### Status codes

| Code  | Description                                                               |
| ----- | ------------------------------------------------------------------------- |
| `201` | Envelope created and sent successfully                                    |
| `400` | Invalid request headers, JSON body, envelope XML, or reusable identifiers |
| `401` | Missing, invalid, or expired authorization token                          |
| `403` | No permission to send envelopes from the specified mailbox                |

### Related topics

{% columns %}
{% column %}

* [Send your first envelope](/introduction/send-your-first-envelope.md)
* [XML payloads](/guides/xml-payloads.md)
* [Templates and reusable IDs](/guides/templates-and-reusable-ids.md)
* [Envelope fields](/guides/envelope-fields.md)
* [Envelope metadata](/guides/envelope-metadata.md)
  {% endcolumn %}

{% column %}

* [Upload Attachments](/api-reference/upload-attachments.md)
* [Fill Envelope](/api-reference/fill-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 %}