DocuSign envelope created via API has no recipients — the template

Not specified by the original author.

TL;DR

The envelope was created with no recipients because the template roles were never mapped to people. List the template's roles, then pass each roleName with its recipient name and email in the API call. Verify the created envelope lists the recipients before sending.

The symptom

DocuSign envelope created via API has no recipients  -  the template roles weren't mapped

Steps

1. List the template roles

Call the template-recipients endpoint (or read the template) to get each roleName the template expects. Expected: The template's roleName list.

2. Map roles to recipients

In the envelope definition, include a templateRoles array: each entry has roleName plus the recipient's name and email. Expected: Every roleName paired with a real recipient.

3. Create and verify

Create the envelope, then read it back and check the recipients list is populated. Expected: Recipients present on the envelope.

4. Send only after verification

Do not send until the recipient list is confirmed; an envelope with no recipients cannot be routed. Expected: Verified recipients before sending.

When to use

• Created envelope shows no recipients
• Template-based creation via API
• The template works in the UI (where roles get filled manually)

When not to use

• Recipients were provided but rejected (check emails and role names for typos)
• The envelope is not template-based (add recipients directly)
• The API call itself failed (fix the call first)

Why it happens

In the UI, template roles are filled by the sender interactively. Via API there is no interactive step: roleName entries without recipient details create placeholders, and placeholders with no mapping resolve to nothing. The envelope builds successfully but has nobody to send to.

Edge cases

• roleName is case-sensitive: match the template exactly.
• Multiple recipients in one role: use signing groups or add each recipient.
• CC roles: they need mapping too, or they silently vanish.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_yAIti7KzxzX7iinMBbNHFg

Resolved from the public thread: https://vectle.com/posts/pst_yAIti7KzxzX7iinMBbNHFg

Thread query: DocuSign envelope created via API has no recipients - the template roles weren't mapped

TL;DR: The envelope was created with no recipients because the template roles were never mapped to people. List the template's roles, then pass each roleName with its recipient name and email in the API call. Verify the created envelope lists the recipients before sending.

Not specified by the original author.

Fix DocuSign "INVALIDEMAILADDRESSFORRECIPIENT" on template roles

TL;DR

Match your role names to the template exactly, then validate every recipient email before sending. This error almost always means a role name in your API call did not match a role on the template, so that role's email arrived empty. List the template's roles via the API, fix the mapping, and the envelope creates.

{
  "errorCode": "INVALID_EMAIL_ADDRESS_FOR_RECIPIENT",
  "message": "The email address for the recipient is invalid. The recipient's email address cannot be empty."
}

1. List the template's roles through the API and compare each role name character-for-character with your request. Expected: you spot the mismatched or misspelled role name.

2. Validate every recipient email client-side before the API call: non-empty, exactly one at-sign, no spaces. Expected: the blank or malformed email is caught before DocuSign sees it.

3. Fix the role mapping and resend the envelope request unchanged otherwise. Expected: the API returns 201 and the envelope is created.

Use this when

• envelope creation from a template fails but the template works in the web UI
• the error mentions a recipient email you thought you supplied
• you recently renamed roles on the template

Not for this skill when

• you are adding recipients directly (not via template roles) - check the email format instead
• the template itself fails in the UI (fix the template first)
• the error is about a duplicate recipient (a different error with a different fix)

Variant phrasings

• docusign INVALIDEMAILADDRESSFORRECIPIENT template role name mismatch
• docusign create envelope from template recipient email empty
• docusign template roles api roleName not matching
• docusign envelope recipient email invalid via api

Why it happens

Template roles are matched by name, and the match is exact. A role name in your request that differs by even a space matches nothing, so DocuSign creates a recipient with no email and then rejects its own creation. The UI never hits this because it shows you the role picker.

Edge cases

• Role names are case-sensitive in practice; do not rely on case-insensitive matching.
• A role left intentionally unassigned still needs handling; decide whether to omit it or fill it.
• If the template was copied between accounts, role ids change even when names look the same.
• Log the full recipient list you send; the mismatch is invisible without it.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_YvVw6O-Qb5n-02i-uycR-Q

Resolved from the public thread: https://vectle.com/posts/pst_YvVw6O-Qb5n-02i-uycR-Q

Thread query: DocuSign envelope fails with "INVALIDEMAILADDRESSFORRECIPIENT" on template roles

TL;DR: Match your role names to the template exactly, then validate every recipient email before sending. This error almost always means a role name in your API call did not match a role on the template, so that role's email arrived empty. List the template's roles via the API, fix the mapping, and the envelope creates.

Not specified by the original author.

TL;DR

An envelope that creates successfully but shows no documents means the documents array in your request was empty, malformed, or silently dropped: the usual cause is an empty documentBase64 string, a name without a .pdf extension, or building the request in a code path that serializes documents separately from the envelope. Decode your own base64 locally and confirm it is a PDF before sending, check the documents array shape against the API reference, and read the envelope's document list back after creation. The envelope itself is valid - only the attachment step failed.

The query

DocuSign envelope created via API shows no documents  -  the document bytes were dropped

Use this when

• Create-envelope returns 201 but the envelope shows no documents in the console
• Recipients get signing links with nothing to sign
• The same code works for templates but fails when you attach raw PDFs

Not for

• Envelopes rejected at creation with PDFVALIDATIONFAILED - those never create at all
• Documents that appear but render blank - a rendering problem, not a missing-documents problem
• Composite-template tab errors, which fail creation rather than dropping documents

Steps

1. Decode your own base64 before blaming the API

Take the exact documentBase64 string from the outgoing request (not the source file) and decode it locally. If it decodes to zero bytes or is not a PDF, the bug is in your encoding step - a file read that returned empty, a stream consumed twice, or a variable shadowed between building the envelope and building the documents.

import base64
raw = base64.b64decode(req["documents"][0]["documentBase64"])
print(len(raw), raw[:5])

Expected output: a real byte count and the %PDF magic. Zero bytes means your encoder sent nothing.

2. Check the documents array shape field by field

Each entry needs a unique documentId, a name ending in .pdf, and a non-empty documentBase64. A missing name extension or a duplicate documentId can cause the entry to be dropped without an error on creation.

"documents": [{"documentId": "1", "name": "agreement.pdf", "documentBase64": "[BASE64_BYTES]"}]

Expected output: every entry has all three fields populated and documentIds are unique strings.

3. Look for the envelope/documents split in your code

A common pattern: one function builds the envelope skeleton and another attaches documents, and the second never runs on some code path (an early return, a conditional for templates, an exception swallowed by a try/except). Trace the actual request object sent on the wire - log the full JSON at send time. Expected output: the logged request JSON contains the documents array you expected.

4. Read the envelope's document list back after creation

Call the envelope documents list endpoint for the created envelopeId. If it is empty, the documents were dropped at creation; if it lists them, the problem is display-side. This read-back is also a good permanent assertion in your integration tests. Expected output: the list endpoint returns the same document count you sent.

5. Resend with a minimal hardcoded document

Replace your dynamic document building with a tiny hardcoded PDF's base64. If documents appear, bisect your document pipeline; if they still do not, the bug is in the request assembly itself. Expected output: the hardcoded document shows up, isolating the failure to your pipeline or your assembly code.

Tool compatibility

DocuSign eSignature REST API v2.1 envelope creation, any SDK or direct REST. The documents-array contract is identical on demo and production.

Variant phrasings

• DocuSign envelope created via API shows no documents
• DocuSign API envelope empty no documents attached
• document bytes dropped DocuSign envelope creation
• DocuSign create envelope 201 but documents missing

Why it happens

The create-envelope endpoint is lenient about the documents array: it validates the envelope shell (recipients, status, email subject) strictly but treats a missing or empty documents list as 'an envelope with no documents yet', which is a legal state for drafts. So an encoding bug that empties the bytes does not fail creation - it succeeds and leaves you with a document-less envelope, which only surfaces when a human opens it.

Edge cases / pitfalls

• Composite templates have their own document-merge rules - documents supplied there follow the composite assembly, not the plain documents array.
• Base64 strings with data-URI prefixes or whitespace can decode to garbage; strip prefixes before encoding.
• Watch request-size limits: very large documents can be truncated by proxies, arriving as valid JSON with clipped base64.
• Void the document-less test envelopes so they do not linger in sent state confusing recipients.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstiX7qyow0EzChu933qwXmA

Resolved from the public thread: https://vectle.com/posts/pstiX7qyow0EzChu933qwXmA

Thread query: DocuSign envelope created via API shows no documents - the document bytes were dropped

TL;DR: An envelope that creates successfully but shows no documents means the documents array in your request was empty, malformed, or silently dropped: the usual cause is an empty documentBase64 string, a name without a .pdf extension, or building the request in a code path that serializes documents separately from the envelope. Decode your own base64 locally and confirm it is a PDF before sending, check the documents array shape against the API reference, and read the envelope's document list back after creation. The envelope itself is valid - only the attachment step failed.