Docusign eSignature REST API 输入无效邮箱无报错问题咨询

问题场景 #

使用DocuSign官方示例代码调用eSignature REST API时，若输入不存在的收件人邮箱，接口仍会返回envelope_id，且status字段为sent，无任何错误信息返回（返回内容如下）：

Please enter the signer's name: saf
Please enter the cc email address: scisaif1@gmail.com
Please enter the cc name: saif
{'bulk_envelope_status': None,
 'envelope_id': 'bd7781a5-ea9e-472d-b087-90baa12b573f',
 'error_details': None,
 'recipient_signing_uri': None,
 'recipient_signing_uri_error': None,
 'status': 'sent',
 'status_date_time': '2022-08-14T10:02:02.9400000Z',
 'uri': '/envelopes/bd7781a5-ea9e-472d-b087-90baa12b573f'}
Your envelope has been sent.

之后才会收到DocuSign的提示邮件：

Documents you sent for electronic signature could not be delivered to this email address: adfasasdfasdgasddf@gmail.com

原因说明 #

DocuSign API返回的sent状态仅表示信封已成功提交至DocuSign系统，进入发送队列，并不代表邮件已成功投递到收件人邮箱。邮箱有效性（是否存在、是否可送达）的校验是DocuSign后台异步执行的操作，不会同步反馈给API调用请求。

解决方案 #

• 通过Webhook实时获取投递状态
  配置DocuSign Connect（Webhook），订阅RecipientDeliveryFailed事件。当收件人邮箱无法投递时，DocuSign会主动将该事件推送到你指定的回调地址，你可以实时获取投递失败的详细信息，包括收件人邮箱和错误原因。

• 主动查询收件人状态
  调用GET /envelopes/{envelopeId}/recipients接口，获取信封下所有收件人的状态。若收件人状态为failed，则说明投递失败，可通过delivery_status和delivery_error_code字段查看具体失败原因。

• 提前做邮箱初步校验
  在创建信封前，自行对收件人邮箱做格式校验（比如检查是否包含@及域名），或通过DNS MX记录查询验证域名是否存在，提前过滤明显无效的邮箱。但这种方式无法完全确保邮箱真实可用，仅能做初步筛选。

内容的提问来源于stack exchange，提问作者Saifullah Rahman