From the Trenches: Enhancing email delivery with Docusign

When you send agreements through Docusign, you expect that recipients will receive, open, and sign them promptly. In most cases, this process is seamless. However, there are instances where email delivery fails or experiences delays, causing disruptions in your workflow. This guide equips developers with the knowledge and tools to recognize, troubleshoot and resolve email delivery issues within the Docusign platform.

Understanding the landscape of email delivery failures

When an email fails to reach its intended recipient, it’s usually due to one of these common causes:

• Invalid email address: This is the most frequent cause. The email address provided for the recipient may contain typos, have extra spaces, or simply not exist.

• Temporary server issues: The recipient’s mail server may be experiencing temporary outages or undergoing maintenance, preventing the email from being delivered at that specific time.

• Blocked or blacklisted emails: In some cases, the recipient’s email server or their email service provider may have filters or security settings that block or flag Docusign emails as spam, preventing them from reaching the recipient’s inbox.

Recognizing and pinpointing delivery failures

Docusign offers developers two primary methods for identifying when an email delivery has failed:

The GetEnvelope API call

By using the GetEnvelope API call and including the include=recipients parameter, you can retrieve detailed information about an envelope’s recipients. Within the recipient object, the status property will indicate the delivery status. A value of "autoresponded" signifies explicitly that the email delivery has failed. Refer to the Docusign API Reference documentation for a complete list of possible status values and their meanings. Sample Request:

curl --location 'https://demo.docusign.net/restapi/2.1/accounts/1…1/envelopes/2...2?include=recipients' \
--header 'Authorization: bearer e…..g'

Sample Response with recipient object:

"status": "autoresponded",
"autoRespondedReason": "The email account that you tried to reach does\n    not exist. ……"

Docusign Connect notifications (recommended)

Connect is the Docusign webhook-based notification system. It’s the preferred method for tracking delivery failures because it provides real-time updates and eliminates the need for continuous API polling. With Connect, you’ll receive instant notifications when a delivery fails and the specific reason for the failure.

Configuring Connect for failure notifications

To leverage Connect for real-time email delivery failure notifications, follow these steps:

• Enable "Autoresponded" status: Contact Docusign Support to ensure that the "autoresponded" status setting is activated within your Docusign account.

• Activate recipient event: In your Connect configuration, enable the "Recipient Auto Responded" recipient event. This ensures that you’ll receive notifications specifically for failed deliveries.

  

• Include recipient data: Include "Recipients" within your Connect configuration's "Include Data" payload. This will provide detailed recipient information in the notification payload, including the delivery status.

  

Interpreting Connect failure notifications

When an email delivery fails, Connect will send a notification containing the following key information:

• Event type: The event field will have the value "recipient-autoresponded", indicating that the recipient’s email server responded automatically, usually due to a delivery failure.

• Recipient status: The status field in the signer object will be "autoresponded".

• Failure reason: The autoRespondedReason field will provide a human-readable explanation for the delivery failure. For example, it might state, "The email account that you tried to reach does not exist."

  

Strategies for resolving delivery failures

Non-existent email address

• Double-check with the signer: The first step is to verify the recipient’s email address directly with them. The address may have been mistyped initially.

• Correct and resend: Once you have the correct email address, update the recipient's information within the envelope and resend it.

Issues with the recipient’s email service provider

• Recipient-side troubleshooting: Sometimes, the recipient may need to contact their IT department or email service provider to resolve the issue. This is particularly relevant if Docusign emails are being blocked or filtered as spam.

• Whitelist Docusign: If Docusign emails are being blocked, advise the recipient or their IT team to whitelist Docusign email domains and IP addresses. This will ensure that Docusign emails are delivered to the recipient's inbox without being blocked or filtered. Docusign provides detailed instructions and information on whitelisting in their support documentation.

Key takeaways

• Proactive monitoring: By implementing Connect notifications and actively monitoring email delivery statuses, you can quickly identify and address delivery failures, ensuring a smooth and efficient signing process.

• Clear communication: When delivery failures occur, clear and timely communication with recipients is crucial. Provide them with guidance on resolving the issue, whether it involves checking their email address or contacting their IT department.

• Leverage Docusign Support: If you encounter persistent delivery issues or have questions about specific failure reasons, don't hesitate to contact Docusign Support for assistance.

Conclusion 

By understanding the common causes of email delivery failures and utilizing the tools and strategies outlined in this guide, you can significantly improve email delivery success rates and enhance the overall user experience when sending contracts through Docusign.

Additional resources

• How to troubleshoot invalid email errors

• From the Trenches: How to fix missing Docusign email notifications for recipients

• Troubleshooting for common errors