Scheduled sending

eSignature REST API 2.1 only

The scheduled sending feature enables you to create an envelope and send it automatically at a specific time. You can define the send time as:

An absolute date and time
A delay from the time an envelope is created

Scheduled sending applies to recipients at the first step of an envelope’s routing order. The routing order defines the sequence in which an envelope is delivered to recipients. Another feature, delayed routing, controls the timing of delivery to subsequent recipients in the routing order. In addition, you can pause envelope delivery before sending to recipients at a step in the routing order, but the pause feature differs from scheduled sending and delayed routing by requiring an API call to resume envelope routing. All three options are part of a suite of eSignature platform features known as Advanced Recipient Routing (ARR).

Note: The scheduled sending feature is available in all developer accounts, but only in certain production account plans. Contact Docusign Support or your account manager to find out whether scheduled sending is available for your production account plan.

Why schedule the sending of an envelope?

By default, an envelope is sent to the initial recipients when you call Envelopes:create, unless you create the envelope as a draft. The scheduled sending feature provides more flexibility. You can create an envelope without immediately sending it, and instead send the envelope exactly when you need to.

You can apply scheduled sending in many common scenarios, including:

Completing all preparations on a Friday for an envelope to be sent to recipients Monday morning
Sending an event registration form on the date when registration opens
Sending an offer of employment 24 hours after a background check has been completed
Sending an insurance policy cancellation notice 10 days after a missed premium payment

Scheduled sending with bulk sending

Scheduled sending supports bulk sending a batch of envelopes to a list of recipients. You can define a bulk list of recipients via a request to BulkSend:createBulkSendList; then, in the Envelopes:create call, define an envelope that will serve as the basis for the bulk send batch envelopes. This envelope definition includes the bulk list ID, as well as a scheduled sending time or delay. When the scheduled sending time arrives, bulk send batch envelopes are generated and sent to recipients in the bulk list. The original envelope generated by the Envelopes:create call is deleted.

Docusign recommends you validate your bulk sending list against an envelope before generating the batch envelopes, to avoid errors when the batch is processed. After you’ve created the bulk list and envelope, make a request to BulkSend:createBulkSendTestRequest to ensure that they are compatible. Correct any issues that the compatibility check finds by updating the envelope or updating the bulk list. You can run the compatibility check and make envelope or bulk list updates at any time prior to the scheduled send time.

Add scheduled sending to a workflow

You can add scheduled sending to an envelope by defining it in the workflow. To implement scheduled sending:

When creating an envelope, include a workflow object.
In the workflow object, include a scheduledSending object.
(Optional) For a bulk send, in the scheduledSending object, include a bulkListId property whose value is the ID of the bulk list.
In the scheduledSending object, include a rules array.
To define when the envelope will be sent, in the rules array, specify a rule object with one of the following properties:
- resumeDate: A specific date and time when the envelope should be sent to recipients. This value is an ISO8601 datetime string with the time zone specified. For example, 2022-04-03T23:30:00Z represents a send date and time of April 3, 2022 at 11:30 PM UTC.
- delay: A delay between the time the envelope is created and the time it is sent, which cannot exceed 30 days. This value is a string in [d.]hh:mm:ss format, defined as:
  - [d]: the number of days from 0 to 30, optional
  - hh: hours from 00 to 23
  - mm: minutes from 00 to 59
  - ss: seconds from 00 to 59

For details and example code, see How to schedule an envelope.

Retrieve, update, and delete scheduled sending parameters

The EnvelopeWorkflowDefinition resource defines endpoints that you can use to retrieve, update, and delete scheduled sending parameters for envelopes.

Cancel a scheduled send

You can cancel a scheduled send in several ways. The option you select will depend on the status of the scheduled send.

Before the countdown has begun, you can call the EnvelopeWorkflowDefinition:deleteEnvelopeScheduledSendingDefinition endpoint.
To end a scheduled send countdown that’s in progress, you can do either of the following:
- Call the EnvelopeWorkflowDefinition:updateEnvelopeScheduledSendingDefinition endpoint and set the send time or delay to one minute in the future. This will reset the countdown, and the envelope will be sent to the recipients one minute later.
- Call the EnvelopeWorkflowDefinition:deleteEnvelopeWorkflowDefinition endpoint. This will leave the envelope in created status. It will not be sent until you make an Envelopes:update request that changes the envelope status to sent.

Behaviors and restrictions

Scheduled sending has the following behaviors and restrictions:

A scheduled send applies to all of an envelope’s initial recipients.
You can schedule sending up to 30 days in the future. This limit applies to both delays and specific send times. When using a specific send time, the 30-day limit applies to the length of time between envelope creation and the resumeDate.
A draft envelope will be deleted automatically 30 days after it is created, regardless of the scheduled sending rules or workflow status. To prevent a draft from being deleted before the send time arrives, set the resumeDate or delay rule of a scheduled sending workflow to send the envelope before the 30-day limit expires.
If you create an envelope as a draft, the delay countdown starts when you send an Envelopes:update call to update the envelope status from created to sent. The envelope status will not actually change to sent until the delay elapses. See Status changes during scheduled sending for details.
If an envelope expires before the scheduled send time arrives, the envelope will not be sent.
While the API supports scheduled sending by delay or at a specific time, the eSignature web app only supports scheduled sending at a specific time. If a user will edit an API-created envelope in the eSignature web application, the scheduled sending definition should include a specific send time rather than a delay.

Envelope statuses

Several types of status are updated as an envelope moves through the scheduled sending process. To track envelope status during a scheduled send, you may need to check all of these status types:

Envelope status: The overall envelope status.
Workflow status: The overall state of the envelope workflow. For more information, see Envelopes:get, scroll down to the Responses section, and on the Definitions tab for a success response, expand the workflow object.
Scheduled sending status: The envelope’s current stage in the scheduled send process. For more information, see Envelopes:get, scroll down to the Responses section, and on the Definitions tab for a success response, expand the scheduledsending object.

Workflow and scheduled sending statuses are not included in Connect messages. To determine the current status, you can use the following calls:

EnvelopeWorkflowDefinition:getEnvelopeScheduledSendingDefinition: Returns the scheduled sending status.
Envelopes:get: If you specify an include query parameter with a value of workflow, this call returns the workflow and scheduled sending statuses, in addition to the envelope status. If you omit the include query parameter, this call does not return workflow and scheduled sending information.
EnvelopeWorkflowDefinition:getEnvelopeWorkflowDefinition: Returns the workflow and scheduled sending statuses.

Note: Do not call these methods more than once every 15 minutes. Making excess calls to check envelope status will violate Docusign polling rules and can increase your risk of being locked out for exceeding API call limits.

Status changes during scheduled sending

Docusign applies the following statuses to envelopes at each stage of scheduled send processing.

Stage	Envelope status	Workflow status	Scheduled sending status
An envelope has been created as a draft (the `status` in the Envelopes:create call was `created`). The scheduled send countdown will not be initiated until an Envelopes:update call changes the `status` from `created` to `sent`.	`created`	`pending`	`pending`
The scheduled send countdown has been initiated, but the time or delay specified for the scheduled send has not arrived or elapsed. The envelope has not been sent yet.	`created`	`scheduled`	`started`
The time or delay specified for the scheduled send has arrived or elapsed. The envelope has been sent. Note: When the scheduled send time arrives for an envelope that includes a bulk list, the original envelope is deleted, and batch envelope processing begins. Workflow status and scheduled sending status are not available for batch envelopes.	`sent`	`completed`	`completed`

Below is an example of part of the JSON response to an Envelopes:get call that shows the envelope, workflow, and scheduled sending statuses:

{
  "status": "created",
  "workflow": {
    "resumeDate": "2022-03-07T16:30:00.0000000Z",
    "workflowStatus": "scheduled",
    "scheduledSending": {
      "status": "started",
      "resumeDate": "2022-03-07T16:30:00.0000000Z",
      "rules": [
        {
          "resumeDate": "2022-03-07T16:30:00.0000000Z"
        }
      ]
    },
    "currentWorkflowStepId": "",
    "workflowSteps": []
  }
}

Status for bulk send batch envelopes after a scheduled send

At the scheduled send time for a bulk send batch, the original envelope created by the Envelopes:create call is deleted, and batch envelopes are generated and sent to the bulk list recipients. To track their status, you’ll need the batch envelope IDs. You can obtain them via these calls:

BulkSend:getBulkSendBatches: Returns a list of bulk send batches, including their IDs, that match query parameters in the request. Use this call to obtain the ID for the batch whose envelopes you want to track. You can then use the batch ID in the requests listed below.
BulkSend:getBulkSendBatchEnvelopes: Returns envelope information, including ID and status, for all batch envelopes associated with the batch ID supplied in the request.
BulkSend:getBulkSendBatchStatus: Returns overall status for the batch ID supplied in the request, including the number of envelopes in sent and completed status.

Error codes

Docusign returns the following codes to report errors related to scheduled sending. The API returns the upper-case error code and the message text.

Error code	Message text	Description
ACCOUNT_LACKS_PERMISSIONS	This Account lacks sufficient permissions.	The request workflow contains `scheduledSending` rules, but the requesting user’s account does not have scheduled sending available in their account plan.
INVALID_REQUEST_PARAMETER	The request contained at least one invalid parameter. Envelope delay rules supports specifying either a ‘resumeDate’ or ‘delay’, but not both.	The request workflow’s `scheduledSending` property contains a `rules` object with a value defined for both the `delay` and `resumeDate` properties. Only one of these properties should be defined.
INVALID_REQUEST_PARAMETER	The request contained at least one invalid parameter. Invalid value for ‘delay’: {delay}.	The request workflow’s `scheduledSending` property contains a `rules` object with an invalid value for the `delay` property. The value must be a timespan string in the format `days.hours:minutes:seconds` with these components: `days`: an optional integer value up to 30, omitted if less than 1 `hours`: two digits between 00 and 23 `minutes`: two digits between 00 and 59 `seconds`: two digits between 00 and 59
INVALID_REQUEST_PARAMETER	The request contained at least one invalid parameter. Invalid value for ‘resumeDate’: {resumeDate}.	The request workflow’s `scheduledSending` property contains a `rules` object with an invalid value for the `resumeDate` property. The value must be a properly formatted ISO8601 datetime string.
INVALID_REQUEST_PARAMETER	The request contained at least one invalid parameter. Invalid value for scheduled sending ‘delay’, must be a positive value {requestWorkflow.ScheduledSending.Rules[0].Delay}.	The request workflow’s `scheduledSending delay` rule differs from the saved workflow’s `scheduledSending delay` rule, and the request `delay` is either zero or a negative timespan.
INVALID_REQUEST_PARAMETER	The request contained at least one invalid parameter. Invalid value for scheduled sending ‘resumeDate’, must not be in the past: {requestWorkflow.ScheduledSending.Rules[0].ResumeDate}.	The request workflow’s `scheduledSending resumeDate` rule differs from the saved workflow’s `resumeDate` rule, and the request’s `resumeDate` is in the past.
INVALID_REQUEST_PARAMETER	The request contained at least one invalid parameter. Invalid value for ‘scheduledSending.rules’, expected rules list to contain at most 1 rule, but {rules.Count} rules were defined.	The request workflow’s `scheduledSending` property contains a `rules` array with more than one `rules` object defined. Only one `rules` object is permitted.
WORKFLOW_UPDATE_NOT_ALLOWED	Update to the workflow is not allowed. Scheduled sending delay has already elapsed, unable to modify scheduled sending delay.	The request workflow defines a `scheduledSending delay` rule that differs from the current state of the workflow’s `scheduledSending delay` rule, and the current `scheduledSending delay` has already elapsed.
WORKFLOW_UPDATE_NOT_ALLOWED	Update to the workflow is not allowed. Unable to delete scheduled sending delay, delay is either in progress or completed.	A request to delete scheduled sending cannot be completed because the countdown to the send time has started or finished. For a countdown in progress, you can use the EnvelopeWorkflowDefinition:updateEnvelopeScheduledSendingDefinition endpoint to update the delay or send time. As an alternative, you can use the EnvelopeWorkflowDefinition:deleteEnvelopeWorkflowDefinition endpoint. This will cancel the countdown and leave the envelope in `created` status. It will not be sent until you make an Envelopes:update request that changes the envelope status to `sent`.

Next steps

For details and example code that demonstrates how to schedule sending for an envelope, see:

How to schedule an envelope

For information about scheduling sending for an envelope in the eSignature web app, see:

Schedule an Envelope to Send at a Future Date and Time

For more features of Advanced Recipient Routing, see:

For information about bulk sending, see: