Manage email notifications for Workflow Sessions

By default, Yousign returns the Workflow Session link in the API response and you are responsible for sharing it with the Applicant.

You can delegate the notifications to Yousign by setting delivery_mode to "email" on an Applicant: the session link at the initialization and the results of the Workflow Sessions will be sent automatically by email.

Choose a delivery mode

The delivery_mode field controls how Yousign notifies an Applicant. It is set at the root of the Applicant object and applies to both natural_person and legal_person types.

When delivery_mode is "email", you must also provide an email field at the root of the Applicant object. This is the address used for all notifications.

You can also provide email while keeping delivery_mode set to "none". The address will be stored but no email will be sent, allowing you to switch to "email" later via PATCH without re-providing the address.

Set the delivery mode on an Applicant

Set delivery_mode and email when creating an Applicant via POST /v3/workflow_sessions/{workflowSessionId}/applicants, or update them later via PATCH /v3/workflow_sessions/{workflowSessionId}/applicants/{applicantId}.

{
  "label": "Kelly Smith",
  "type": "natural_person",
  "delivery_mode": "email",
  "email": "[email protected]",
  "natural_person": {
    "identity": {
      "first_name": "Kelly",
      "last_name": "Smith"
    }
  }
}

If delivery_mode is "email" and email is absent or null, the request returns a 400 validation error.

Session link notification

When you call GET /v3/workflow_sessions/{workflowSessionId}/links, Yousign generates the session link and (if delivery_mode is "email") sends it by email to the Applicant's delivery address. The Applicant transitions to notified and the existing applicant.notified webhook fires. The link is also returned in the API response.

Send-once rule: the email is sent only on the first call, when the Applicant transitions from initiated to notified. If the Applicant is already notified, subsequent calls return the link without sending a new email. This lets you safely retrieve the link again without triggering a duplicate notification.

The session link expires after 48 hours. If an Applicant lands on an expired link, the interface shows a button to regenerate a new one, which automatically sends a new email (when delivery_mode is "email"). When delivery_mode is "none", no regeneration button is shown and the Applicant sees an error page and it is your responsibility to call GET /links again and redistribute the new link.

There is no reminder endpoint in V1. To re-share the link, call GET /links and distribute it manually.

Result notification

When the Workflow Session reaches done or blocked, Yousign automatically sends a result notification email to the same delivery address. No email is sent when the session is in ongoing status.

A new verification can be added to an Applicant after it reaches processed status — for example, a second KYC check a few days later. When the Applicant transitions back from processed to notified, a new session link email is sent.

Applicant status reference

Sandbox

delivery_mode and email are fully supported in sandbox. When calling GET /links in sandbox with delivery_mode: "email", an email is dispatched to the real delivery address (with a sandbox sender). This lets you test the full email flow end-to-end. For general guidance on testing Workflow Sessions, see Testing Workflow Session Links in Sandbox.

V1 scope: all emails are sent in English, regardless of the Applicant's locale. Locale-based email language is planned for V2.