Keep clients in step and send each season
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:writeandsends: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
- A group for the season:
POST /v1/groups(or find it withGET /v1/groups). - 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. - One request to the group:
POST /v1/sendswithgroupIds, the note andconfirmation. AddsendAtto send later. - Follow it:
GET /v1/sends/{id}, and/resultsfor 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=…(theasOfof your last call): changed people and the ids of deleted ones. Contacts are deleted automatically after 24 months without activity. - A
batch.finishedevent (and webhook) says when a send is done;contact.unsubscribedwhen 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.