Email API

Everything the portal does with email can be done from the API. Docustay never sends general email: only mail about a document your workspace made, to the people named on it.

Per document

Add an email object to a send or a draft:

await docustay.sendDocument({
  templateId, parties,
  email: { subject: "Your agreement", message: "Thanks for choosing us.", replyTo: "hello@example.com", senderName: "Example Co", locale: "fr" },
});

locale is a language code such as en, es or fr, or auto to match each person. Every field is optional.

Templates

await docustay.listEmailTemplates();                                  // every message, with saved wording where there is any
await docustay.saveEmailTemplate("invitation", { subject: "{{org.name}} sent you {{document.title}}", locale: "en" });
await docustay.previewEmailTemplate("invitation", { subject: "…" });  // what it would look like, nothing sent
await docustay.resetEmailTemplate("invitation");                      // back to the built-in wording

The message types are invitation, reminder, completed, declined, voided, expired, code and receipt. Reading needs the templates:read scope and changing needs templates:write.

The log

const { emails, nextCursor } = await docustay.listEmails({ documentId, status: "bounced", limit: 50 });

You can filter by document, recipient (to), status and kind. A status is one of sent, delivered, bounced, complained, failed, skipped, paused and limit_reached. The same list is in Developers → Email events.

Webhooks

Subscribe a webhook to documents.email.delivered, documents.email.bounced and documents.email.complained. They carry ids only, never an address. documents.email.paused tells you sending was paused for the workspace.

Safe by design

Mail goes only to people named on the document. Sending pauses by itself for a workspace when 2% of its recent email bounces or 0.05% is reported as spam, once at least 50 emails have gone out in 30 days, so one bad list cannot harm your domain's name. Platform → Domains and email shows how close you are.