{"api":"esign_rest","category":"reference"}

BulkSend Resource

You can use bulk send lists for anything that you need to send to a large number of recipients on a recurring basis, such as:

  • Compliance letters (privacy, security, and ethics consent forms)
  • New hire onboarding documents (benefits, transit, and parking information and payroll forms)
  • Other Human Resources documents
  • Event-related forms

The API creates a separate copy of the envelope for each recipient that you specify. Each instance of the envelope is called a BulkCopy. You can use a bulk send list to send up to 1,000 copies per call.

After you create a bulk send list, it persists and can be reused and edited any number of times.

Customizing Bulk Send Lists

You can customize individual copies of the envelope. For example, you can customize the email notification and language and add personalized notes.

For example, if one recipient prefers to access their DocuSign envelopes behind an access code, and another prefers her email in French, you can implement those customizations.

Using Bulk Send

The bulk send feature uses the following flow:

  1. Create a draft envelope by calling the Envelopes::createEnvelope method. Add placeholders for bulk send information to the envelope, including:
  2. Email address placeholders.
  3. Tab placeholders. Assign tabLabels to these placeholders that will make sense for matching the tabs to values in the bulk send list. For example, if you're sending a field trip permission slip to parents, you might create a placeholder text tab called StudentName that will you will then populate with the names of individual students in the bulk send list. You can use the following types of text tabs, radio group tabs, and list tabs to match bulk send recipients to an envelope.
  4. Any envelope custom fields. These fields must match the envelope custom fields in envelope copies in the bulk send list.
  5. Create a bulk send list by using the BulkSend::createBulkSendList method.
  6. (Optional) Test compatibility. Use the BulkSend::createBulkSendTestRequest method to test your bulk send list for compatibility with the envelope or template that you want to send. For example, a template that has three roles is not compatible with a bulk send list that has only two recipients. For this reason, you might want to test compatibility first. A successful test result returns the Boolean value true. An unsuccessful test returns a JSON response that contains information about the errors that occurred.
  7. Send your envelope to the list by using the BulkSend::createBulkSendRequest method. The response returns a batchId that you can use for tracking and other purposes.

The API creates and queues your envelopes asynchronously behind the scenes. You can get the status of the batch by using the BulkEnvelopes_GetBulkEnvelopesBatchId method, passing in the batchId.

To get the envelopes generated for the batchId, use the Envelopes_GetEnvelopes method, passing in a custom_field named BulkBatchId where the value is the batchId that was returned in step 4.

Example:

custom_field=BulkBatchId={{batchId}}

Bulk Send Requirements and Limitations

  • Bulk send must be enabled for your account (in the accountSettingsInformation object, enableBulkRecipient must be set to true) and for the user sending the envelopes (the allowBulkRecipients property in userSettings must be set to true).
  • When you send an envelope with bulk recipients, envelopes are added to a bulk recipient queue and sent in a metered fashion. An account can have a total of 2,000 envelopes in the queue at a time. If this limit is reached, an error message displays to the sender. If you receive this error, wait and resend the envelope at a later time.

If you frequently run into queue limits, contact your account manager to discuss modifying the queue limits for your account.

For more information about using bulk send, see Bulk Sending Envelopes.

MethodDescription
getBulkSendLists
GET /v2.1/accounts/{accountId}/bulk_send_lists

Gets bulk send lists

createBulkSendList
POST /v2.1/accounts/{accountId}/bulk_send_lists

Creates a bulk send list

getBulkSendList
GET /v2.1/accounts/{accountId}/bulk_send_lists/{bulkSendListId}

Gets a specific bulk send list

updateBulkSendList
PUT /v2.1/accounts/{accountId}/bulk_send_lists/{bulkSendListId}

Updates a bulk send list

deleteBulkSendList
DELETE /v2.1/accounts/{accountId}/bulk_send_lists/{bulkSendListId}

Deletes a bulk send list

createBulkSendRequest
POST /v2.1/accounts/{accountId}/bulk_send_lists/{bulkSendListId}/send

Creates a bulk send request

createBulkSendTestRequest
POST /v2.1/accounts/{accountId}/bulk_send_lists/{bulkSendListId}/test

Creates a bulk send test

}} />