通过代码添加DocuSign信封收件人后邮件未发送的问题咨询

我正在开发一个通过代码动态添加DocuSign信封收件人的系统，已在DocuSign端创建模板，使用该模板ID发送信封的PHP代码如下：

$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);
}

目前观察到DocuSign模板中的收件人列表已正确更新，但邮件并未自动发送，仅在再次发起发送请求后，信封才会被发送。请问这是预期行为吗？是否需要预先在模板中填写收件人列表才能正常发送信封？

问题解答 #

1. 这不是预期行为：当你在EnvelopeDefinition中设置status: 'sent'时，调用createEnvelope接口应该直接触发信封发送流程，无需二次请求。
2. 不需要预先在模板中填写收件人：通过template_roles动态绑定收件人到模板角色是DocuSign API支持的标准用法，完全可以替代模板预设收件人。
3. 可能的问题排查方向：
   • 角色名称匹配问题：确认代码中role_name: 'passenger'与模板中定义的角色名称完全一致（包括大小写、空格、特殊字符）。如果名称不匹配，DocuSign会忽略该收件人，导致信封没有有效收件人，无法自动发送。
   • 账户ID正确性：检查$accountInfo[0]->getAccountId()返回的账户ID是否与模板所属的账户一致，用错账户会导致异常行为。
   • 查看DocuSign日志：登录DocuSign后台，进入「账户」→「监控」→「日志」，查看创建信封时的具体日志条目，是否有错误或警告提示（比如收件人邮箱格式问题、模板权限不足等）。
   • API调用完整性：确认createEnvelope接口调用是否完整执行，没有被异步逻辑或错误中断。可以在调用后打印$envelopResults的详细信息，看是否返回了正确的信封ID和状态。
   • 环境配置问题：如果使用沙箱环境，偶尔会有轻微延迟，但不会需要二次请求才能发送。确认API客户端的环境配置（沙箱/生产）是否正确，Token是否有效。

内容的提问来源于stack exchange，提问作者Frisbetarian-Support Palestine