Docusign: Is there a way to create an envelope in the 'created' state and then put it into 'sent' later?

Question

I want to be able to create an envelope and then email the link to the signer. The code segment I came up with is:

EnvelopesApi envelopesApi = new EnvelopesApi();

        envDef.Status = "sent";
        EnvelopeSummary envelopeSummary = envelopesApi.CreateEnvelope(accountId, envDef);

        RecipientViewRequest viewOptions = new RecipientViewRequest()
        {
            ReturnUrl = "https://www.docusign.com/devcenter", 
            ClientUserId = signer.ClientUserId,
            AuthenticationMethod = "email",
            UserName = signer.Name,
            Email = signer.Email // does NOT send an email
        };

        ViewUrl recipientView = envelopesApi.CreateRecipientView(accountId, envelopeSummary.EnvelopeId, viewOptions);

The code before this segment gets the account, signer an envelope definition, etc.

This code works fine if I set envDef.Status = "sent". If I do not set that status, I get an exception from the last line of code in this segment.

I want to just have the envelope go into created status, then get the URL and send the email in my own code that does relay email.

Or, can I supply an email address and have Docusign send the email? But, in that case, what if their email fails for some reason?

The bottom line is that I want a way to deal with the problem of how to re-send the link if the email fails to get sent.

Answer 1

Re your stated objective:

I want to just have the envelope go into created status, then get the URL and send the email in my own code that does relay email.

This approach is not recommended, since the URL that you obtain via CreateRecipientView will timeout in a short amount of time (I believe it's 5 minutes). In other words, if the recipient does not open the email that you send them and click the link to launch their signing session within that period of time, the link becomes invalid and they'll be unable to use it to access their signing session.

Instead of using CreateRecipientView , I'd recommend that you simply specify the recipient's info (name, email, etc.) as part of the envelope definition and then DocuSign will send the recipient an email that contains a link that they can use to access their Envelope. This link will be valid for days (not minutes, like the link that you generate yourself via CreateRecipientView ), so there's no requirement that the signer act on it immediately. If for some reason the recipient misplaces or does not receive the email that DocuSign sends them, you can easily have DocuSign re-send that email notification by either using the DocuSign web UI or by using the UpdateRecipient API operation with resendEnvelope=true specified (as Frederic described in his answer).

---

Update #1

There's no way to retrieve a long-lived link that a recipient can use to initiate their signing session. A common way to address your scenario would be the following:

• Send the signer an email that contains a link that leads them to a web page that you build -- and instructions for them to click that link to launch their Envelope whenever they are ready to review/sign the document(s) . (The link URL would need to contain some sort of querystring parameters that your web page could use to identify the Envelope and Recipient.)

• Design your web page such that when it receives an inbound request (as it would when the recipient clicks the link in the email you send them), it uses the information in the querystring parameters to identify the Envelope and Recipient, then issues a CreateRecipientView request to retrieve the URL that will launch that recipient's signing session, and finally, automatically redirects the user to the URL that the CreateRecipientView response returns, thereby opening the Envelope for the recipient to review/sign/submit.

By following a process like this, you're able to craft/send the email that the recipient receives (instead of relying upon DocuSign to do so), and can ensure that you're only retrieving the envelope URL whenever the user has indicated that they're ready to sign (thereby avoiding the potential of the short-lived link expiring before it's used).

---

Update #2

For an example of how to add recipient(s) to the EnvelopeDefinition object using the DocuSign C# SDK, see this " recipe " -- specifically, see the code within the requestSignatureOnDocumentTest method. It's basically a two-step process:

1) Define each recipient. For example:

// Add a recipient to sign the documeent
Signer signer = new Signer();
signer.Email = recipientEmail;
signer.Name = recipientName;
signer.RecipientId = "1";

2) Populate the Recipients property of the EnvelopeDefinition object with the recipient(s) that you create. For example:

envDef.Recipients = new Recipients();
envDef.Recipients.Signers = new List<Signer>();
envDef.Recipients.Signers.Add(signer);

Answer 2

I'm going to try to answer both of your inquiries :

1) The bottom line is that I want a way to deal with the problem of how to re-send the link if the email fails to get sent.

In order to re-send the DocuSign email to your recipients, you can use the UpdateRecipient() method as such (see my C# example below). This will re-trigger the signing email to be sent one more time to the transaction recipients :

RecipientsUpdateSummary recipientsUpdateSummary = 
                envelopeApi.UpdateRecipients(
                    accountId, 
                    envelope.EnvelopeId, 
                    envelope.Recipients, 
                    new EnvelopesApi.UpdateRecipientsOptions { resendEnvelope = "true" });

Here is what the official documentation states :

2) Is there a way to create an envelope in the 'created' state and then put it into 'sent' later?

Yes, it is possible. When you create your envelope, make sure to specify the "Created" status as below :

Status = "created"

Create your envelope :

envelopeApi.CreateEnvelope(accountId, envelope);

Then, when you're ready, change the envelope status to "sent". This will trigger the emails to the recipients. Voila !

Envelope updatedEnvelope = new Envelope
            {
                Status = "sent"
            };
            envelopeApi.Update(
                accountId,
                envelopeId,
                updatedEnvelope);