# Fix DocuSign "INVALID_EMAIL_ADDRESS_FOR_RECIPIENT" 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.

```text
{
  "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 INVALID_EMAIL_ADDRESS_FOR_RECIPIENT 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