fastify-x-signwell

bulkSend.*

Send a SignWell template to many recipients at once using bulk-send — create, list, validate CSV, and inspect results.

bulkSend.*

Send one template to many recipients in a single operation. Each recipient gets their own individual document. Supports CSV-based recipient data, validation before submission, and result inspection.

Signatures

fastify.xsignwell.bulkSend.create(params: {
  templateId: string;
  recipients: Array<Record<string, unknown>>;
  subject?: string;
  message?: string;
  testMode?: boolean;
}): Promise<Object>

fastify.xsignwell.bulkSend.get(bulkSendId: string): Promise<Object>

fastify.xsignwell.bulkSend.list(
  params?: { page?: number; limit?: number }
): Promise<Object>

fastify.xsignwell.bulkSend.getCsvTemplate(templateId: string): Promise<Object>

fastify.xsignwell.bulkSend.validateCsv(
  templateId: string,
  csvContent: string
): Promise<Object>

fastify.xsignwell.bulkSend.getDocuments(
  bulkSendId: string,
  params?: { page?: number; limit?: number }
): Promise<Object>

Params

create

Name	Type	Required	Description
`params.templateId`	`string`	Yes	ID of the template to use.
`params.recipients`	`array`	Yes	Non-empty array of recipient row objects matching the template's recipient placeholders.
`params.subject`	`string`	No	Email subject override.
`params.message`	`string`	No	Email message override.
`params.testMode`	`boolean`	No	Override plugin-level test mode for this bulk send.

get / getDocuments

Name	Type	Required	Description
`bulkSendId`	`string`	Yes	ID of the bulk send operation.
`params.page`	`number`	No	Page number (getDocuments only).
`params.limit`	`number`	No	Results per page (getDocuments only).

list

Name	Type	Required	Description
`params.page`	`number`	No	Page number.
`params.limit`	`number`	No	Results per page.

getCsvTemplate

Name	Type	Required	Description
`templateId`	`string`	Yes	Template ID to generate the CSV template for.

validateCsv

Name	Type	Required	Description
`templateId`	`string`	Yes	Template ID the CSV is for.
`csvContent`	`string`	Yes	Raw CSV string to validate.

Returns

Method	Returns
`create`	The created bulk send object with `id` and `status`.
`get`	Bulk send details including `status`, `document_count`, `completed_count`.
`list`	Paginated list of bulk send summaries.
`getCsvTemplate`	Object with CSV template content for building recipient rows.
`validateCsv`	Validation result object with `valid` flag and any `errors`.
`getDocuments`	Paginated list of individual documents generated by the bulk send.

Throws

[xSignwell] bulkSend.create: params object is required
[xSignwell] bulkSend.create: templateId (string) is required
[xSignwell] bulkSend.create: recipients (non-empty array) is required
[xSignwell] bulkSend.get: bulkSendId (string) is required
[xSignwell] bulkSend.getCsvTemplate: templateId (string) is required
[xSignwell] bulkSend.validateCsv: templateId (string) is required
[xSignwell] bulkSend.validateCsv: csvContent (string) is required
[xSignwell] bulkSend.getDocuments: bulkSendId (string) is required
Re-throws SignWell API errors with statusCode and signwellError properties.

Examples

create — send to multiple recipients

const bulkSend = await fastify.xsignwell.bulkSend.create({
  templateId: "tmpl_nda",
  recipients: [
    { signer_1_email: "alice@example.com", signer_1_name: "Alice" },
    { signer_1_email: "bob@example.com", signer_1_name: "Bob" },
    { signer_1_email: "carol@example.com", signer_1_name: "Carol" },
  ],
  subject: "Your NDA is ready to sign",
});

console.log(bulkSend.id); // "bulk_abc123"

getCsvTemplate + validateCsv — validate before submit

// Get the CSV column structure for the template
const csvTemplate = await fastify.xsignwell.bulkSend.getCsvTemplate("tmpl_nda");
console.log(csvTemplate); // tells you what columns are expected

// Validate your CSV data before sending
const validation = await fastify.xsignwell.bulkSend.validateCsv(
  "tmpl_nda",
  "signer_1_email,signer_1_name\nalice@example.com,Alice\nbob@example.com,Bob"
);

if (!validation.valid) {
  console.error("CSV validation errors:", validation.errors);
}

getDocuments — inspect individual results

const docs = await fastify.xsignwell.bulkSend.getDocuments("bulk_abc123");

for (const doc of docs.documents) {
  console.log(doc.id, doc.status); // individual document IDs and statuses
}

Realistic — employee handbook bulk sign

fastify.post("/hr/handbook/send", async (request, reply) => {
  const employees = await db.employees.findActive();

  const recipients = employees.map((emp) => ({
    employee_email: emp.email,
    employee_name: emp.fullName,
    hire_date: emp.hireDate,
  }));

  const bulkSend = await fastify.xsignwell.bulkSend.create({
    templateId: process.env.HANDBOOK_TEMPLATE_ID,
    recipients,
    subject: "Action Required: Please sign the updated employee handbook",
  });

  await db.hrEvents.insert({
    type: "handbook_bulk_send",
    bulkSendId: bulkSend.id,
    recipientCount: recipients.length,
  });

  return reply.send({ bulkSendId: bulkSend.id, sent: recipients.length });
});

AI Context

package: "@xenterprises/fastify-xsignwell"
methods: fastify.xsignwell.bulkSend.create(params) | get(bulkSendId) | list(params?) | getCsvTemplate(templateId) | validateCsv(templateId, csvContent) | getDocuments(bulkSendId)
use-when: Send a SignWell template to many recipients at once — each recipient gets their own document

Edit this pageorReport an issue

fastify-x-signwell

Fastify plugin for SignWell e-signature API — document creation, template management, bulk sending, and webhook handling.

documents.create

Create a new SignWell document and send it to one or more recipients for signing.