Share access to your mailbox or individual envelopes

Share individual envelopes

You can share individual envelopes securely with any users in your account using the Individual Envelope Sharing feature. This feature provides a simple way to share individual envelopes with other account users without also sharing your entire mailbox (as with shared access to your mailbox) or using insecure workarounds such as emailing documents directly or using third-party services. This ensures that every collaborative action is tracked in the envelope’s history.

Levels of access for shared envelopes

Users can assign specific permissions per share:

• View, which enables users to read and download the envelope.
• Edit, which enables users to correct, resend, void, read, and download the envelope.
• Manage, which enables users to edit and send a draft envelope as well as all of the above permissions.

The following example API call shares an envelope with another user in within an account:

POST /restapi/v2.1/accounts/08b4799a-xxxx-xxxx-xxxx-b5b4b8a97604/envelopes/2a1a24ef-xxxx-xxxx-xxxx-3962899702af/shares
{
  "shares": [
    {
      "customMessage": "I’m sharing this example envelope with you",
      "permission": "view",
      "agentUser": {
        "accountId": "08b4799a-xxxx-xxxx-xxxx-b5b4b8a97604",
        "userId": "babe89bc-xxxx-xxxx-xxxx-c7a694be15b9"
      }
    }
  ]
}

Sharing individual envelopes is currently only supported by the Docusign eSignature API (UI support is in development) by calling the individual envelope sharing endpoints:

• EnvelopeShares: createEnvelopesShares: Allows an eligible user to share the envelope with one or many users within the same account.
• EnvelopeShares: updateEnvelopesShares: Allows an eligible user to update the share access level for one or more users at a time.
• EnvelopeShares: updateEnvelopesShare: Allows an eligible user to update the single share access level for one user at a time.
• EnvelopeShares: deleteEnvelopesShares: Allows the envelope owner or admin to revoke access for one or more users.
• EnvelopeShares: deleteEnvelopesShare: Allows the envelope owner or admin to revoke access for one particular user.
• EnvelopeShares: getEnvelopesShares: Allows the envelope owner or admin to retrieve all shares for a given envelope.
• EnvelopeShares: getEnvelopesShare: Allows the envelope owner or admin to retrieve single share information for a given envelope.
• EnvelopeShares: getSharedEnvelopes: Returns a paginated list of envelopes that the user has access to through Individual Sharing or via Tickets/Agreement Desk. This endpoint also supports advanced search functionality across shared envelopes, supporting wildcard searches on subject, sender, and recipient fields.

Agentic limitations and behavior

• Only the sender of an individual envelope or an account admin can share that envelope.

• A maximum of 100 agents are supported per API request.

• A maximum of 100 agents are supported per Envelope.

• Agents will receive email notification when the sender shares an envelope with them.

• Agents can use the emailed envelope share link and perform actions on the envelope based on permission level granted to their user.

• To perform an action on a shared envelope, agents must include the ?use_sharing=true query parameter in every API request. For example:

  GET /v2.1/accounts/{accountId}/envelopes/{envelopeId}?use_sharing=true

Shared access to your mailbox

The mailbox shared access feature enables you to send and manage envelopes on behalf of other users in your account. Using shared access, you can manage an account user’s envelope inbox, send, and even set up a delegate to sign envelopes on their behalf. Shared access is often used for delegating work when a colleague is unavailable or for teams who use a shared account for sending and managing envelopes.

You can use shared access through the Docusign eSignature UI or the Authorizations resource.

• The UI enables you to use the full range of shared access functionality, including sharing access from one user to another, sending an envelope on behalf of another user, or managing envelopes on behalf of another user. See Shared access to envelopes for details on using this feature through the UI.
• The API enables you to manage shared access permissions between your account users. Future releases may expand upon this functionality to call API endpoints that enable you to match all shared access UI functionality using the API.

Managing authorizations

You can use the Authorization REST API to create, update, and delete authorizations for your account’s users. An authorization is the set of permissions granted to one user (an agent) within your account to act on behalf of another (a principal). Once an authorization is created, the agent user may then use shared access to send, manage, or sign envelopes on behalf of the principal user, depending on the type of authorization that was granted. All API calls an agent makes must include the header X-Specific-Header: {AGENT_ACCOUNT_ID} to authenticate and identify the agent making the request.

Note: To create an authorization for a user in your account, you must create the authorization as the principal or be an admin for your account.

There are four types of authorization that a principal user can grant to an agent to act on their behalf:

• Manage: Enables the agent to manage envelopes on behalf of the principal user as though they were the principal. Agents with the manage permission cannot send envelopes on behalf of the principal.
• Send: Enables the agent to send and manage envelopes on behalf of the principal user.
• Sign: Enables the agent to sign envelopes on behalf of the principal user. This is used for the Delegated signing feature.
• Edit: Enables the agent to manage envelopes on behalf of the principal user, just like the manage permission, but also enables the agent to correct, void, and resend envelopes.

When you create or update an authorization in the API, you choose the type of authorization by setting the permission field in the request body to send, manage, edit, or sign.

Note: Sending and managing envelopes on behalf of other users has specific Docusign eSignature plan requirements. Contact your account representative for more information.

The following table shows which envelope actions are supported by each permission:

Next steps

• See how to How to share access to an envelope inbox.
• Read the Authorizations resource for full details of the API.
• See Shared access to envelopes for details on using this feature through the UI.