SignWell can bulk-send eSignatures from a CSV by combining a reusable template with recipient and field data. Each CSV row supplies the data for one generated document, and each document is tracked independently. The official CLI can generate the correct CSV headers, validate the file, create the bulk send, and list the documents it produces.

This workflow is useful for offer letters, NDAs, policy acknowledgments, renewal agreements, attestations, and any other process that sends the same template to a list of people. SignWell currently documents a limit of 500 recipients per bulk send, so larger lists must be split into separate files.

Who Should Use Bulk Send eSignatures?

• HR and People teams are sending offer letters, onboarding documents, NDAs, or policy acknowledgments.
• Procurement teams distributing vendor agreements or annual NDA updates.
• Customer Success and Revenue Operations teams are sending renewals or standardized amendments.
• Legal and Compliance teams running attestation or updated-terms campaigns.
• Engineering teams launch eSignature batches from an HRIS, CRM, scheduled job, or internal tool.

Bulk sending is designed for repeated documents with structured recipient data. If every agreement has a different language or a different field layout, create separate templates or use the document API instead of forcing unrelated documents into one CSV.

What You Need Before You Start

1. A SignWell account with API access and an API key from the Settings > API page.
2. A SignWell template with one or more placeholder roles and labeled fields.
3. A CSV whose columns match the placeholder names and field labels in the template.
4. Node.js 18 or newer if you plan to use the SignWell CLI.

Install and authenticate the CLI:

npm install -g @signwell/cli
sw auth login –api-key YOUR_API_KEY

How SignWell Maps CSV Columns to a Template

Bulk-send columns are based on the placeholder name in the template. The recipient email column is required. Names and labeled field values are optional unless your workflow requires them.

For a placeholder named Candidate and fields labeled start_date, salary, and manager_name, a CSV can look like this:

candidate_email,candidate_name,candidate_start_date,candidate_salary,candidate_manager_name
[email protected],Jane Smith,2026-05-15,”$120,000″,Sam Wehbe
[email protected],Alex Lee,2026-05-20,”$135,000″,Sam Wehbe

• Column names are not case-sensitive.
• Spaces in column headers work the same as underscores.
• Field labels must still match. A template field labeled phone will not map to a CSV column labeled phone number.
• Wrap values containing commas in double quotes so the CSV remains valid.
• Use one column set for every placeholder included in the template.

Best Practice: Do not build the header row from memory. Generate the CSV template from SignWell so the placeholder and field names match exactly.

How To Bulk Send eSignatures With The CLI

1. Build The SignWell Template

Create a template in the SignWell dashboard and add the placeholder roles required for the agreement. Add labels to text fields that should be populated from the CSV. For example, an offer-letter template can use a Candidate placeholder with field labels such as start_date, salary, and manager_name.

Save the template and copy its UUID. The commands below use TEMPLATE_UUID as a placeholder.

2. Generate The Correct CSV Template

sw bulk-send csv-template \
  –template TEMPLATE_UUID \
  -o recipients.csv

The generated file contains the required and optional columns supported by the selected template. The CLI and API can also accept more than one template ID when a workflow combines multiple templates into a single bulk-send document.

3. Add Recipient And Field Data

Enter one generated document per row. A row can contain more than one recipient when the template has multiple placeholders. Keep the generated headers intact, and review spreadsheet exports for converted dates, missing leading zeros, or commas that were not quoted correctly.

4. Validate The CSV

Validate before creating the bulk send. The validation command checks the CSV structure and data and returns row-level errors when it finds them:

sw bulk-send validate \
  –template TEMPLATE_UUID \
  –csv recipients.csv

The create command also supports –dry-run, which performs validation without creating the bulk send. You can use either validation method; running both is not required.

sw bulk-send create \
  –template TEMPLATE_UUID \
  –csv recipients.csv \
  –dry-run

5. Create The Bulk Send

sw bulk-send create \
  –template TEMPLATE_UUID \
  –csv recipients.csv \
  –name “May Offer Letters” \
  –confirm

–confirm skips the interactive confirmation prompt. Omit it when a person should review the command before submitting the request.

6. Monitor The Bulk Send And Its Documents

sw bulk-send list
sw bulk-send get BULK_SEND_ID
sw bulk-send documents BULK_SEND_ID

The first command lists bulk sends, the second returns one bulk-send resource, and the third lists the documents generated by that batch. Individual documents can also be monitored through the Documents area and API.

Bulk-Send Limits and Pilot Batches

The SignWell Help Center documents a maximum of 500 recipients per bulk send. Split larger campaigns into CSV files that contain 500 or fewer recipients. When one row includes multiple placeholders, count all recipients represented in that row toward the limit.

For a high-impact campaign, start with a small pilot. The CLI supports –limit to process only the first N rows:

sw bulk-send create \
  –template TEMPLATE_UUID \
  –csv recipients.csv \
  –limit 10 \
  –name “Offer Letter Pilot” \
  –confirm

Duplicate Warning: After a limited pilot, remove the processed rows or create a new CSV containing only the remaining recipients. Running the original full CSV again can create a second document for the pilot recipients.

Create a Bulk Send Directly Through the API

The Create Bulk Send endpoint does not accept an array of recipient objects. It accepts one or more template UUIDs and the complete CSV as an RFC 4648 base64 string. The endpoint validates the CSV before creating the bulk send.

import { readFile } from ‘node:fs/promises’;

const csv = await readFile(‘recipients.csv’);

const response = await fetch(
  ‘https://www.signwell.com/api/v1/bulk_sends’,
  {
    method: ‘POST’,
    headers: {
      ‘X-Api-Key’: process.env.SIGNWELL_API_KEY,
      ‘Content-Type’: ‘application/json’,
      ‘Accept’: ‘application/json’
    },
    body: JSON.stringify({
      template_ids: [process.env.SIGNWELL_TEMPLATE_ID],
      bulk_send_csv: csv.toString(‘base64’),
      skip_row_errors: false,
      name: ‘May Offer Letters’
    })
  }
);

if (!response.ok) {
  const body = await response.text();
  throw new Error(`Bulk send failed: ${response.status} ${body}`);
}

const bulkSend = await response.json();
console.log(‘Bulk send ID:’, bulkSend.id);

The API also provides a CSV-template endpoint so application code can retrieve the exact required and optional columns for one or more template IDs. Use that generated schema instead of maintaining a separate hard-coded header list.

How Row Errors Are Handled

The API parameter skip_row_errors defaults to false. With the default setting, row errors should be fixed before the bulk send is created. This is the safest behavior when every recipient must receive a document and partial processing would be difficult to reconcile.

Set skip_row_errors to true only when partial processing is intentional and your integration records which rows were rejected. The CLI documentation does not provide a separate skip-row-errors option, so CLI workflows should validate and correct the CSV before sending it.

Operational Practices for Bulk Sending

• Generate the CSV template from the exact SignWell template version used for the send.
• Give each bulk send a unique, descriptive name and store the returned bulk-send ID with the source campaign or job.
• Use a pilot file for legal, compensation, renewal, or compliance documents where a mapping error would be costly.
• Split campaigns before they exceed the documented 500-recipient limit.
• Validate again after any spreadsheet edit or export, even if the file was validated earlier.
• Use sw bulk-send documents or the corresponding API endpoint to reconcile document-level status.
• Use document webhooks for granular automation. The Help Center notes that senders and CC recipients do not receive an email for every individual document view or completion in a bulk send.

In the SignWell dashboard, the recipient detail view and export options can help review signed, unsigned, and all recipients. Be careful with cancellation: the Help Center states that canceling a bulk send deletes all documents in the batch, while Remove Recipients cancels the remaining unsigned documents.

Common Bulk-Send Workflows

Offer Letters and Onboarding Documents

Export the approved cohort from the HRIS, map the data to generated template columns, validate the CSV, and send a small pilot before the full batch.

Vendor and Partner Agreements

Use one placeholder for the external signer and labeled fields for company, agreement date, or account owner. Store the bulk-send ID with the procurement campaign for reconciliation.

Policy Acknowledgments and Attestations

Split the employee population into files that remain within the recipient limit, then aggregate document_completed events into the campaign record.

Customer Renewals

Generate the list from the CRM, include the customer-specific terms supported by labeled fields, and route completion events back to the correct account using the SignWell document ID.

Conclusion

To bulk send eSignatures reliably, start with a well-defined SignWell template, generate the CSV headers from that template, validate the completed file, and create batches that stay within the 500-recipient limit. Store the bulk-send ID, monitor the generated documents, and use webhooks when downstream systems need document-level status in real time.

Related SignWell Resources

• SignWell Help Center: Bulk Sending
• SignWell API: Create Bulk Send
• SignWell API: Get Bulk Send CSV Template
• SignWell API: Validate Bulk Send CSV
• SignWell API: Get Bulk Send Documents
• SignWell CLI on GitHub