Skip to content

Cookbook

Send reminders on a schedule

A daily job that resends the signing request to recipients who haven't signed yet, and skips the ones the resend limits don't allow.

Run a job once a day. It lists envelopes still in progress and resends the signing request to every recipient who was sent one and hasn’t completed, if their envelope is more than two days old.

Node.js
const API = "https://api.signatureapi.com/v1";
const headers = { "X-API-Key": process.env.SIGNATUREAPI_KEY, "Content-Type": "application/json" };
const TWO_DAYS = 2 * 24 * 60 * 60 * 1000;

export async function sendReminders() {
  let url = `${API}/envelopes?status=in_progress&limit=20`;

  while (url) {
    const page = await (await fetch(url, { headers })).json();

    for (const envelope of page.data) {
      if (Date.now() - Date.parse(envelope.created_at) < TWO_DAYS) continue;

      for (const recipient of envelope.recipients) {
        if (recipient.status !== "sent" && recipient.status !== "soft_bounced") continue;

        const res = await fetch(`${API}/recipients/${recipient.id}/resend`, {
          method: "POST",
          headers,
          body: JSON.stringify({}),
        });
        // 409: too early, no more resends, or not an email link ceremony. Skip it until the next run.
        if (!res.ok && res.status !== 409) console.error(recipient.id, res.status);
      }
    }
    url = page.links.next;
  }
}
Python
import os
from datetime import datetime, timedelta, timezone

import requests

API = "https://api.signatureapi.com/v1"
HEADERS = {"X-API-Key": os.environ["SIGNATUREAPI_KEY"]}


def send_reminders():
    url = f"{API}/envelopes?status=in_progress&limit=20"
    cutoff = datetime.now(timezone.utc) - timedelta(days=2)

    while url:
        page = requests.get(url, headers=HEADERS).json()

        for envelope in page["data"]:
            if datetime.fromisoformat(envelope["created_at"].replace("Z", "+00:00")) > cutoff:
                continue

            for recipient in envelope["recipients"]:
                if recipient["status"] not in ("sent", "soft_bounced"):
                    continue

                res = requests.post(f"{API}/recipients/{recipient['id']}/resend", headers=HEADERS, json={})
                # 409: too early, no more resends, or not an email link ceremony. Skip it until the next run.
                if not res.ok and res.status_code != 409:
                    print(recipient["id"], res.status_code)

        url = page["links"]["next"]
  • Limits are enforced for you. A resend before can_resend_at returns 409 too-early-to-resend, and the tenth email is the last: after that you get too-many-attempts. The first invitation counts as one. See the wait periods.
  • Only email links. Resend works for recipients whose ceremony uses email_link authentication, in an in_progress envelope. A recipient waiting their turn in a sequential envelope is still pending, so the job skips them until they are sent a request.
  • Your own wording. The resend body accepts subject_override and message_override to change that one email.
  • Pace. A daily job stays well inside the 15 minute and 1 hour waits. Test envelopes send no email: use a live envelope, or read the test emails in the Dashboard.