SealDrop Book a demo

Keep clients in step and send each season

Developers · Guides

For: Accounting and tax software. Once a season, your system puts its client list into a SealDrop group (new people added, existing ones updated) and sends everyone in it one secure request — sent gradually, with the same safety stops as the app.

Before you start

  • A live key with contacts:write and sends:write (the Full access preset). Group sends reach real people, so test keys can't start one.
  • Group sending on the organization's plan, and its bulk-sending terms accepted once by an admin in the app (New request → Group or everyone).
  • Permission: each person you add must have agreed to hear from the organization. Your call says so (consent), and it is recorded with your key and the admin who made it.

The steps

  1. A group for the season: POST /v1/groups (or find it with GET /v1/groups).
  2. Your clients into it, 500 at a time: POST /v1/contacts/bulk. New people are added; anyone already there (same email or mobile) has their name updated and joins the group; unusable rows are skipped with the reason — one result per row.
  3. One request to the group: POST /v1/sends with groupIds, the note and confirmation. Add sendAt to send later.
  4. Follow it: GET /v1/sends/{id}, and /results for who it went to and what happened.

The code

Complete, in your language. Put your key in SEALDROP_API_KEY; replace the lines marked your code with your own. These exact samples run against the API in SealDrop's tests.

# 1. A group for the season (once)
curl -X POST https://api.sealdrop.ca/v1/groups \
  -H "Authorization: Bearer $SEALDROP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Tax season 2026"}'

# 2. Your clients, up to 500 a call: new ones added, existing ones updated, all put in the group
curl -X POST https://api.sealdrop.ca/v1/contacts/bulk \
  -H "Authorization: Bearer $SEALDROP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "consent": { "confirmed": true },
    "contacts": [
      { "name": "Jordan Lee", "email": "jordan@example.com", "groupIds": ["'"$GROUP_ID"'"] },
      { "name": "Sam Patel", "email": "sam.patel@example.ca", "groupIds": ["'"$GROUP_ID"'"] }
    ]
  }'

# 3. One request to everyone in the group, sent in waves within sending hours
curl -X POST https://api.sealdrop.ca/v1/sends \
  -H "Authorization: Bearer $SEALDROP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "groupIds": ["'"$GROUP_ID"'"],
    "note": "Please upload your 2026 tax slips.",
    "confirmation": { "confirmed": true }
  }'

# 4. Who it went to, and what happened
curl https://api.sealdrop.ca/v1/sends/$SEND_ID/results \
  -H "Authorization: Bearer $SEALDROP_API_KEY"
const API = 'https://api.sealdrop.ca';
const headers = { Authorization: `Bearer ${process.env.SEALDROP_API_KEY}`, 'Content-Type': 'application/json' };
const call = async (method, path, body) => {
  const res = await fetch(API + path, { method, headers, body: body && JSON.stringify(body) });
  if (!res.ok) throw new Error((await res.json()).error.code);
  return res.json();
};

// The season's group: found, or made once.
const { groups } = await call('GET', '/v1/groups');
const group = groups.find((g) => g.name === 'Tax season 2026') ?? (await call('POST', '/v1/groups', { name: 'Tax season 2026' }));

// Your clients (from your own system), 500 at a time. You confirm each agreed to hear from you.
const clients = await yourClientsThisSeason(); // your code: [{ name, email }]
for (let i = 0; i < clients.length; i += 500) {
  const { created, updated, skipped, results } = await call('POST', '/v1/contacts/bulk', {
    consent: { confirmed: true },
    contacts: clients.slice(i, i + 500).map((c) => ({ ...c, groupIds: [group.id] })),
  });
  console.log({ created, updated, skipped });
  for (const r of results.filter((r) => r.result === 'skipped')) console.log('row', r.index, r.reason);
}

// One request to the whole group. It goes out in waves; follow it with GET /v1/sends/{id}.
const started = await call('POST', '/v1/sends', {
  groupIds: [group.id],
  note: 'Please upload your 2026 tax slips.',
  confirmation: { confirmed: true },
});
console.log(started.status, started.queued, 'queued');
import os, requests

API = "https://api.sealdrop.ca"
s = requests.Session()
s.headers["Authorization"] = f"Bearer {os.environ['SEALDROP_API_KEY']}"

def call(method, path, body=None):
    res = s.request(method, API + path, json=body, timeout=30)
    res.raise_for_status()
    return res.json()

# The season's group: found, or made once.
group = next((g for g in call("GET", "/v1/groups")["groups"] if g["name"] == "Tax season 2026"), None)
if group is None:
    group = call("POST", "/v1/groups", {"name": "Tax season 2026"})

# Your clients (from your own system), 500 at a time. You confirm each agreed to hear from you.
clients = your_clients_this_season()  # your code: [{"name": ..., "email": ...}]
for i in range(0, len(clients), 500):
    batch = [{**c, "groupIds": [group["id"]]} for c in clients[i:i + 500]]
    result = call("POST", "/v1/contacts/bulk", {"consent": {"confirmed": True}, "contacts": batch})
    print(result["created"], "created,", result["updated"], "updated,", result["skipped"], "skipped")

# One request to the whole group. It goes out in waves; follow it with GET /v1/sends/{id}.
started = call("POST", "/v1/sends", {
    "groupIds": [group["id"]],
    "note": "Please upload your 2026 tax slips.",
    "confirmation": {"confirmed": True},
})
print(started["status"], started["queued"], "queued")

Good to know

  • Sends go out in waves within sending hours, at the organization's daily limit, and pause by themselves on too many bounces or a spam report. People without an email, marked don't contact, who unsubscribed, bounced or reported before, or were sent one recently are skipped.
  • Retrying is safe: a second send while one is going is refused (409 batch_active).
  • Keep in step during the year with GET /v1/contacts?updatedSince=… (the asOf of your last call): changed people and the ids of deleted ones. Contacts are deleted automatically after 24 months without activity.
  • A batch.finished event (and webhook) says when a send is done; contact.unsubscribed when someone opts out.

Try it safely

Build the contacts part with any key, then send to a small group of your own team's addresses with a live key before the real one. Each send has its results (/results) and, for admins in the app, the consent proof.

← The API guide · Reference · Changelog