Docusign programatically adding recipients

I'm working on a system where I need to add envelope recipients programmatically.

I created a template on Docusign' side and then I'm using that template's Id to send out the envelopes to each recipient like so

    $planeType = $flight->planeType;
    $passengers = $flight->passengers;

    $TemplatesApi = new TemplatesApi();
    $TemplatesApi->setApiClient($apiClient);

    $templateId = $planeType->docusign_template_id;

    $recipientRoles = [];
    foreach ($passengers as $passenger) {
        $recipientRoles[] = new TemplateRole([
            'email' => $passenger->email,
            'name' => $passenger->name,
            'role_name' => 'passenger',
        ]);
    }

    $envelopeDefinition = new EnvelopeDefinition([
        'email_subject' => 'Please sign this waiver.',
        'template_id' => $templateId,
        'template_roles' => $recipientRoles,
        'status' => 'sent',
    ]);

    try {
        $envelopesApi = new EnvelopesApi($apiClient);
        $envelopResults = $envelopesApi->createEnvelope($accountInfo[0]->getAccountId(), $envelopeDefinition);

        if ($envelopResults) {
            $envelopeStatus = $envelopesApi->getEnvelope($accountInfo[0]->getAccountId(), $envelopResults->getEnvelopeId());

            if ($envelopeStatus->getStatus() === 'sent') {
                return response()->json(['message' => 'Waivers sent successfully', 'envelopeId' => $envelopResults->getEnvelopeId()]);
            } else {
                return response()->json(['message' => 'Failed to send waivers', 'envelopeStatus' => $envelopeStatus->getStatus()], 500);
            }
        } else {
            return response()->json(['message' => 'Failed to update envelope status', 'error' => 'Unknown error'], 500);
        }
    } catch (\Exception $e) {
        return response()->json(['message' => 'Error sending waivers', 'error' => $e->getMessage()], 500);
    }

I can see the list of recipients in the Docusign template view get updated correctly, but the emails do not get sent out. Its only after i issue another request to send do the envelopes get sent.

Is that intended behavior? Does the template need to have a list of prefilled recipients before i can send envelopes to them?

Solution

Yes, that is intended behavior.

You cannot "send" a template, you cannot request signatures on a templates, no one can sign or act on a template.

A template is just a way to create envelopes. It helps you because you can create similar type of envelopes again and again without having to specify the documents or tabs every time. The recipients can also be modified from the template if you need to.

An envelope that was already sent and awaiting signature cannot be modified directly by APIs, you need to first put it in "correct" mode to start a correction process. If the envelope is still in "draft" mode - you can still modify it.

I recommend (but it's not required) that you use the composite template method (instead of the code you share) which affords a lot more flexibility if your needs change later.

Here is some PHP code showing composite templates - https://github.com/docusign/code-examples-php/blob/master/src/Services/Examples/eSignature/AddDocToTemplateService.php