> You are reading the Docusign Developer Documentation. For clean Markdown of any page, append .md to the page URL. > > Documentation indexes by section: > - APIs and SDKs: https://docusign.docs.buildwithfern.com/docs/llms.txt > - Platform 101: https://docusign.docs.buildwithfern.com/platform/llms.txt > - Extension Apps: https://docusign.docs.buildwithfern.com/extension-apps/llms.txt > - Docusign CLI: https://docusign.docs.buildwithfern.com/docusign-cli/llms.txt > > Authentication (OAuth, JWT Grant, M2M): https://docusign.docs.buildwithfern.com/platform/auth > Webhooks and Connect: https://docusign.docs.buildwithfern.com/platform/webhooks > > OpenAPI specifications: https://docusign.docs.buildwithfern.com/openapi.json > MCP server: https://docusign.docs.buildwithfern.com/_mcp/server # Scheduled sending > The Advanced Recipient Routing (ARR) features let you control the flow of envelopes through the signature process by scheduling an envelope to be sent automatically at a specific time. 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](/docs/esign-rest-api/esign101/concepts/recipients/delayed-routing), controls the timing of delivery to subsequent recipients in the routing order. In addition, you can [pause envelope delivery](/docs/esign-rest-api/esign101/concepts/recipients/pause-unpause-workflow) 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](/docs/esign-rest-api/how-to/unpause-workflow). 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](https://support.docusign.com/s/contactSupport) 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](/docs/esign-rest-api/reference/envelopes/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](/docs/esign-rest-api/esign101/concepts/envelopes/bulk-send) a batch of envelopes to a list of recipients. You can define a bulk list of recipients via a request to [BulkSend:createBulkSendList](/docs/esign-rest-api/reference/bulkenvelopes/bulksend/createbulksendlist); then, in the [Envelopes:create](/docs/esign-rest-api/reference/envelopes/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](/docs/esign-rest-api/reference/bulkenvelopes/bulksend/createbulksendtestrequest) to ensure that they are compatible. Correct any issues that the compatibility check finds by [updating the envelope](/docs/esign-rest-api/reference/envelopes/envelopes/update) or [updating the bulk list](/docs/esign-rest-api/reference/bulkenvelopes/bulksend/updatebulksendlist). 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: 1. When [creating an envelope](/docs/esign-rest-api/reference/envelopes/envelopes/create), include a `workflow` object. 2. In the `workflow` object, include a `scheduledSending` object. 3. (Optional) For a bulk send, in the `scheduledSending` object, include a `bulkListId` property whose value is the ID of the bulk list. 4. In the `scheduledSending` object, include a `rules` array. 5. 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](https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations) 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](/docs/esign-rest-api/how-to/schedule-an-envelope). ## Retrieve, update, and delete scheduled sending parameters The [EnvelopeWorkflowDefinition](/docs/esign-rest-api/reference/envelopes/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](/docs/esign-rest-api/esign101/concepts/recipients/scheduled-sending#status-changes-during-scheduled-sending). * Before the countdown has begun, you can call the [EnvelopeWorkflowDefinition:deleteEnvelopeScheduledSendingDefinition](/docs/esign-rest-api/reference/envelopes/envelopeworkflowdefinition/deleteenvelopescheduledsendingdefinition) endpoint. * To end a scheduled send countdown that’s in progress, you can do either of the following: * Call the [EnvelopeWorkflowDefinition:updateEnvelopeScheduledSendingDefinition](/docs/esign-rest-api/reference/envelopes/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](/docs/esign-rest-api/reference/envelopes/envelopeworkflowdefinition/deleteenvelopeworkflowdefinition) endpoint. This will leave the envelope in `created` status. It will not be sent until you make an [Envelopes:update](/docs/esign-rest-api/reference/envelopes/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](/docs/esign-rest-api/reference/envelopes/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](/docs/esign-rest-api/esign101/concepts/recipients/scheduled-sending#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](https://apps-d.docusign.com/send/documents/) 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](/docs/esign-rest-api/esign101/concepts/envelopes/status-codes#envelope-status-code-descriptions)**:** The overall envelope status. * **Workflow status:** The overall state of the envelope workflow. For more information, see [Envelopes:get](/docs/esign-rest-api/reference/envelopes/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](/docs/esign-rest-api/reference/envelopes/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](/platform/webhooks/connect) messages. To determine the current status, you can use the following calls: * [EnvelopeWorkflowDefinition:getEnvelopeScheduledSendingDefinition](/docs/esign-rest-api/reference/envelopes/envelopeworkflowdefinition/getenvelopescheduledsendingdefinition): Returns the scheduled sending status. * [Envelopes:get](/docs/esign-rest-api/reference/envelopes/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](/docs/esign-rest-api/reference/envelopes/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](/docs/esign-rest-api/esign101/rules-and-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](/docs/esign-rest-api/reference/envelopes/envelopes/create) call was `created`). The scheduled send countdown will not be initiated until an [Envelopes:update](/docs/esign-rest-api/reference/envelopes/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](/docs/esign-rest-api/reference/envelopes/envelopes/get) call that shows the envelope, workflow, and scheduled sending statuses: ```text { "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](/docs/esign-rest-api/reference/envelopes/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](/docs/esign-rest-api/reference/bulkenvelopes/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](/docs/esign-rest-api/reference/bulkenvelopes/bulksend/getbulksendbatchenvelopes): Returns envelope information, including ID and status, for all batch envelopes associated with the batch ID supplied in the request. * [BulkSend:getBulkSendBatchStatus](/docs/esign-rest-api/reference/bulkenvelopes/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](https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations) 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](/docs/esign-rest-api/reference/envelopes/envelopeworkflowdefinition/updateenvelopescheduledsendingdefinition) endpoint to update the delay or send time. As an alternative, you can use the [EnvelopeWorkflowDefinition:deleteEnvelopeWorkflowDefinition](/docs/esign-rest-api/reference/envelopes/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](/docs/esign-rest-api/reference/envelopes/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](/docs/esign-rest-api/how-to/schedule-an-envelope) For information about scheduling sending for an envelope in the [eSignature web app](https://apps-d.docusign.com/send/documents/), see: * [Schedule an Envelope to Send at a Future Date and Time](https://support.docusign.com/s/document-item?bundleId=gav1643676262430\&topicId=gqr1647981165582.html) For more features of Advanced Recipient Routing, see: * [Delayed routing](/docs/esign-rest-api/esign101/concepts/recipients/delayed-routing) * [How to send an envelope with delayed routing](/docs/esign-rest-api/how-to/send-envelope-with-delayed-routing) * [Pause and unpause a signature workflow](/docs/esign-rest-api/esign101/concepts/recipients/pause-unpause-workflow) * [How to pause a signature workflow](/docs/esign-rest-api/how-to/pause-workflow) * [How to unpause a signature workflow](/docs/esign-rest-api/how-to/unpause-workflow) * [Specify conditional recipients](/docs/esign-rest-api/esign101/concepts/recipients/conditional-recipients) * [How to use conditional recipients](/docs/esign-rest-api/how-to/use-conditional-recipients) For information about bulk sending, see: * [Bulk sending envelopes](/docs/esign-rest-api/esign101/concepts/envelopes/bulk-send) * [How to bulk send envelopes](/docs/esign-rest-api/how-to/bulk-send-envelopes)