SealDrop API
Quick start
- An admin of the organization opens Settings → Developers in SealDrop, creates a key (start with a test key) and gives it to you. It is shown once: keep it in a secrets vault or password manager.
- Call the API with the key in the
Authorizationheader:
curl https://api.sealdrop.ca/v1/me \
-H "Authorization: Bearer $SEALDROP_API_KEY"const res = await fetch('https://api.sealdrop.ca/v1/me', {
headers: { Authorization: `Bearer ${process.env.SEALDROP_API_KEY}` },
});
if (!res.ok) throw new Error((await res.json()).error.code);
const me = await res.json();
console.log(me.organization.name, me.key.scopes);import os, requests
res = requests.get(
"https://api.sealdrop.ca/v1/me",
headers={"Authorization": f"Bearer {os.environ['SEALDROP_API_KEY']}"},
timeout=30,
)
res.raise_for_status()
me = res.json()
print(me["organization"]["name"], me["key"]["scopes"])Guides
Step by step, with complete code in curl, JavaScript and Python — every sample on these pages runs against the API in our tests, so it keeps working.
Send a request
When a file opens in your system — a deal, a new client, a case — send the secure link from there. It goes out exactly as from the app: the organization's wording, branding, link lifetime and limits.
curl -X POST https://api.sealdrop.ca/v1/requests \
-H "Authorization: Bearer $SEALDROP_API_KEY" \
-H "Idempotency-Key: deal-48213" \
-H "Content-Type: application/json" \
-d '{
"person": { "name": "Amara Okafor", "email": "amara.okafor@example.com" },
"note": "Please upload your last two pay stubs and a photo ID."
}'const API = 'https://api.sealdrop.ca';
const headers = { Authorization: `Bearer ${process.env.SEALDROP_API_KEY}`, 'Content-Type': 'application/json' };
// Once, at start-up: the questionnaire to send with each new deal (made in SealDrop).
const { questionnaires } = await (await fetch(`${API}/v1/questionnaires`, { headers })).json();
const intake = questionnaires.find((q) => q.name === 'Mortgage intake');
// Whenever a deal opens in your CRM:
async function onDealOpened(deal) {
const res = await fetch(`${API}/v1/requests`, {
method: 'POST',
// The deal's id: if this call times out and you retry, the person still gets one email.
headers: { ...headers, 'Idempotency-Key': `deal-${deal.id}` },
body: JSON.stringify({
person: { name: deal.clientName, email: deal.clientEmail },
note: 'Please upload your last two pay stubs and a photo ID.',
...(intake ? { questionnaireId: intake.id } : {}),
}),
});
if (!res.ok) throw new Error((await res.json()).error.code);
const { request } = await res.json();
return request.id; // keep it on the deal: webhooks and events name it
}
await onDealOpened({ id: 48213, clientName: 'Amara Okafor', clientEmail: 'amara.okafor@example.com' });import os, requests
API = "https://api.sealdrop.ca"
s = requests.Session()
s.headers["Authorization"] = f"Bearer {os.environ['SEALDROP_API_KEY']}"
# Once, at start-up: the questionnaire to send with each new deal (made in SealDrop).
questionnaires = s.get(f"{API}/v1/questionnaires", timeout=30).json()["questionnaires"]
intake = next((q for q in questionnaires if q["name"] == "Mortgage intake"), None)
def on_deal_opened(deal):
body = {
"person": {"name": deal["client_name"], "email": deal["client_email"]},
"note": "Please upload your last two pay stubs and a photo ID.",
}
if intake:
body["questionnaireId"] = intake["id"]
# The deal's id: if this call times out and you retry, the person still gets one email.
res = s.post(f"{API}/v1/requests", json=body, headers={"Idempotency-Key": f"deal-{deal['id']}"}, timeout=30)
res.raise_for_status()
return res.json()["request"]["id"] # keep it on the deal: webhooks and events name it
on_deal_opened({"id": 48213, "client_name": "Amara Okafor", "client_email": "amara.okafor@example.com"})The full guide: send a request when a deal or file opens →
- Idempotency-Key is required: any id of yours (your record's id is ideal). If your call times out and you retry with the same key and body, you get the first answer back instead of a second email. Same key, different body →
409 idempotency_mismatch. Keys are remembered 24 hours. questionnaireIdcomes fromGET /v1/questionnaires,emailDesignIdfromGET /v1/email-designs;channelscan add"sms"when texts are on the organization's plan.- The answer says what happened on each channel (
delivery). Later:POST /v1/requests/{id}/resend,/cancelor/filed. - In the app, these requests are marked Sent by API with the key's name.
Pull documents into your system
The whole loop, in four calls. A request is received once the person has submitted; its files are malware-scanned within a minute or two.
- Find what arrived: poll
GET /v1/events(keep itsnextCursor) and act onrequest.receivedandrequest.file_scanned— or listGET /v1/requests?status=received. - Read it:
GET /v1/requests/{id}— who it was from, the note and reply, and its files with their scan status. Questionnaire answers as data:GET /v1/requests/{id}/answers. - Download every clean file:
GET /v1/files/{id}/downloadgives a link valid 5 minutes; fetch it without the Authorization header and store the bytes in your system. - Confirm the import:
POST /v1/requests/{id}/imported. SealDrop then deletes its copy — files, answers and reply — right away, as when staff mark a request Filed, so the documents live in one place: your system. (An organization can choose to have its staff look first; then it is deleted on its usual schedule.) It is refused (409 not_downloaded) until every clean file has been downloaded, so nothing is deleted that you didn't fetch.
# 1. What arrived: requests the person submitted, not yet imported
curl "https://api.sealdrop.ca/v1/requests?status=received" \
-H "Authorization: Bearer $SEALDROP_API_KEY"
# 2. One request: who it's from, the note and reply, its files and their scan status
curl https://api.sealdrop.ca/v1/requests/$REQUEST_ID \
-H "Authorization: Bearer $SEALDROP_API_KEY"
# 3. For each clean file: a 5-minute link (fetch "url" without the Authorization header)
curl https://api.sealdrop.ca/v1/files/$FILE_ID/download \
-H "Authorization: Bearer $SEALDROP_API_KEY"
# 4. The questionnaire answers as data (when the request had one)
curl https://api.sealdrop.ca/v1/requests/$REQUEST_ID/answers \
-H "Authorization: Bearer $SEALDROP_API_KEY"
# 5. It's all in your system: SealDrop deletes its copy
curl -X POST https://api.sealdrop.ca/v1/requests/$REQUEST_ID/imported \
-H "Authorization: Bearer $SEALDROP_API_KEY"const API = 'https://api.sealdrop.ca';
const headers = { Authorization: `Bearer ${process.env.SEALDROP_API_KEY}` };
const get = async (path) => {
const res = await fetch(API + path, { headers });
if (!res.ok) throw new Error((await res.json()).error.code);
return res.json();
};
const { requests } = await get('/v1/requests?status=received');
for (const r of requests) {
const detail = await get(`/v1/requests/${r.id}`);
if (detail.files.some((f) => f.scan === 'pending')) continue; // try again in a minute
for (const f of detail.files.filter((f) => f.scan === 'clean' && !f.deleted)) {
const { url } = await get(`/v1/files/${f.id}/download`);
const bytes = Buffer.from(await (await fetch(url)).arrayBuffer());
await saveToYourSystem(r, f.name, bytes); // your code
}
if (detail.questionnaire) await saveAnswers(r, await get(`/v1/requests/${r.id}/answers`)); // your code
const done = await fetch(`${API}/v1/requests/${r.id}/imported`, { method: 'POST', headers });
if (!done.ok) throw new Error((await done.json()).error.code);
}import os, requests
API = "https://api.sealdrop.ca"
s = requests.Session()
s.headers["Authorization"] = f"Bearer {os.environ['SEALDROP_API_KEY']}"
def get(path):
res = s.get(API + path, timeout=30)
res.raise_for_status()
return res.json()
for r in get("/v1/requests?status=received")["requests"]:
detail = get(f"/v1/requests/{r['id']}")
if any(f["scan"] == "pending" for f in detail["files"]):
continue # try again in a minute
for f in detail["files"]:
if f["scan"] == "clean" and not f["deleted"]:
url = get(f"/v1/files/{f['id']}/download")["url"]
save_to_your_system(r, f["name"], requests.get(url, timeout=60).content) # your code
if detail["questionnaire"]:
save_answers(r, get(f"/v1/requests/{r['id']}/answers")) # your code
s.post(f"{API}/v1/requests/{r['id']}/imported", timeout=30).raise_for_status()The full guide: pull received documents into a client file →
Reading never marks a request as seen for staff; downloading counts like a staff download (it starts the request's deletion clock). If your system downloads but never confirms, SealDrop still deletes the files on the organization's schedule.
Webhooks
Instead of polling, let SealDrop tell your system the moment something happens. An admin adds your https:// address in Settings → Developers → Webhooks, chooses the events (or all) and live or test, and gives you the endpoint's signing secret (whsec_…, shown once). Webhooks are managed only there — never through the API — so a leaked API key can't redirect them.
Each event is a POST with a small JSON body — ids and the event type only, never a name, an address, a file name or an answer. Fetch the details with your API key.
{
"id": "evt_0c7f5e2a-1b3d-4f6a-8c9e-2d4f6a8b0c1e",
"type": "request.received",
"createdAt": "2026-10-23T17:42:10.000Z",
"apiVersion": "v1",
"data": {
"requestId": "5d0b8c2a-7e1f-4a3b-9c4d-2e6f8a0b1c3d"
}
}
Headers: SealDrop-Event-Id, SealDrop-Event-Type, and SealDrop-Signature: t=1792780930,v1=5257a8… — an HMAC-SHA256 of "{t}.{body}" with your secret. Always check it, on the raw body, and refuse anything older than 5 minutes. After an admin gives the endpoint a new secret, messages carry a v1= for each secret for 24 hours.
Node:
const crypto = require('node:crypto');
// rawBody: the request body exactly as received (a string), before any JSON parsing.
function verifySealDrop(rawBody, signatureHeader, secret, toleranceSeconds = 300) {
const items = signatureHeader.split(',').map((part) => part.split('='));
const t = Number(items.find(([k]) => k === 't')?.[1]);
if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;
const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest();
return items.some(([k, v]) => k === 'v1' && v?.length === 64 && crypto.timingSafeEqual(Buffer.from(v, 'hex'), expected));
}
Python:
import hashlib, hmac, time
def verify_sealdrop(raw_body: bytes, signature_header: str, secret: str, tolerance: int = 300) -> bool:
items = [part.split("=", 1) for part in signature_header.split(",")]
t = next((v for k, v in items if k == "t"), None)
if t is None or abs(time.time() - int(t)) > tolerance:
return False
expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
return any(k == "v1" and hmac.compare_digest(v, expected) for k, v in items)
- Answer with any 2xx within 10 seconds (do the work afterwards). Anything else is retried after 1 minute, 5, 30, then hourly for 24 hours; then the endpoint is paused and the organization's admins are emailed. Nothing is lost: the same events stay readable for 30 days with
GET /v1/events. - Deliveries can arrive more than once or out of order: use the event
idto skip duplicates, and read the request for its current state. - SealDrop only calls public HTTPS addresses on port 443, checked at every delivery (never private, internal or cloud-metadata addresses), doesn't follow redirects and never reads your response body.
- Send test in the app delivers a
webhook.testevent (no data) so you can check your signature code.
Contacts, groups and group sends
Keep the organization's SealDrop contacts in step with your system, and send a request to a whole group — with the same rules as in the app.
# 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")The full guide: keep clients in step and send each season →
- Consent is required. Adding someone needs
"consent": {"confirmed": true}: you confirm they agreed to be contacted by the organization. It is recorded with your key and the admin who created it. - One contact per email and per mobile.
POST /v1/contactsanswers409 duplicate_email(orduplicate_phone) with the existingcontactId.POST /v1/contacts/bulk(up to 500 at a time) creates the new, updates the name and groups of anyone already there, and skips invalid rows — one result per row, in order. - Sync only what changed:
GET /v1/contacts?updatedSince=…with theasOfof your last call returns changed contacts and the ids of deleted ones. - People who unsubscribe or are marked don't contact stay that way:
doNotContactcan be set through the API, never cleared. Contacts are deleted automatically after 24 months without activity (deleteOn). - Groups:
/v1/groups, andPOST /v1/groups/{id}/memberswithaddandremove.
- Group sends (
POST /v1/sends) need group sending on the organization's plan and its bulk-sending terms accepted in the app. They go out in waves within sending hours, at the organization's daily limit, with the same safety stops for bounces and spam reports. AddsendAtto schedule one (it appears under/v1/scheduled). Retrying is safe: a second send while one is going is refused (409 batch_active), and anyone sent a request recently is skipped. - Follow them with
GET /v1/sends/{id}and/results;/pause,/resumeand/cancelwork as in the app. Abatch.finishedevent (and webhook) says when one is done. - Group sends reach real people, so only a live key can start one (
403 live_keys_only). Build with a test key on single requests first. - Forms: questionnaires (
/v1/questionnaires, as SurveyJS JSON within what SealDrop allows) and open links (/v1/open-links; the address is returned once, when made or replaced). - Still only in the app: accepting the bulk-sending terms, opt-in pages, and clearing don't contact.
Authentication
- Keys look like
sd_live_…(live) orsd_test_…(test) and go only in theAuthorization: Bearerheader. A key found in a URL, a query string or a body is refused (key_in_url) and not processed — treat that key as exposed and give it a new secret. - SealDrop stores only a one-way hash of each key; nobody, including SealDrop, can show it again.
- Admins choose what each key may do (its scopes), can limit it to your IP addresses, and choose when it expires (30 days to 2 years). Every admin is emailed when a key is created, given a new secret, revoked or about to expire.
- New secret: the previous secret keeps working for 24 hours, so you can switch without downtime. Revoke: the key stops on its very next call.
- Unknown, revoked and expired keys all get the same
401 invalid_key.
Scopes
| Scope | Allows |
|---|---|
requests:read | Status, dates, who it was sent to, the note and the reply message |
files:read | Download links to scanned, clean files, and confirming an import |
answers:read | Questionnaire answers as data |
requests:write | Send, resend, cancel and mark filed |
audit:read | Who did what and when (no personal details) |
contacts:read | Contacts and groups |
contacts:write | Add, update and delete contacts and groups |
sends:write | Group and everyone sends, now or scheduled, and their results |
forms:read | Questionnaires, email designs, open links and opt-in pages |
forms:write | Create and change questionnaires, designs, open links and opt-in pages |
Presets in the app: Pull documents (4 scopes), Send and pull (6 scopes), Full access (10 scopes).
Matching people to your records
SealDrop never compares people against your records: it gives your system complete, consistently named data, and your system decides who is who.
- Who: every request has
person.email(as given) andperson.mobile(E.164, e.g.+16045550123); every contact the same, plusdateOfBirth(YYYY-MM-DD) when known. - Where from:
sourceon requests (app,api,open_linkwithopenLinkId,group_send,recurring) and on contacts (app,api,import,signup_pageoropen_linkwithsourceId). - Answers:
GET /v1/requests/{id}/answersnames fixed fields the same everywhere —dateOfBirth, andidNumberwhen asked — and the organization's own questionsq1,q2…. A question keeps its name when questions are moved or reworded, and a removed question's name is never reused, so a mapping made once keeps working. Questions an open link asks before the person continues are namedd_and the question's id, and its own ID field (a file or client number) isclientNumber. When an open link doesn't ask for a name,person.nameis empty. A contact'ssignupholds what they answered on a sign-up page, with each question as asked. - When: subscribe to
request.received(someone submitted, including on an open link) andcontact.created(someone was added — by staff, the API, a sign-up page or an open link; not each row of an import, which you can sync withupdatedSince).
A sensible order: email, then mobile, then name with date of birth — and a person to review anything that doesn't match exactly.
Test mode
Build against a sd_test_ key; switch to a live one when you're ready. Live keys need SealDrop's approval: when your integration works with a test key, an admin presses Request live access in Settings → Developers and says what you're connecting; we look at the test activity and switch live keys on, usually within a business day. Until then a live key is refused (403 live_access_required). A test key works like a live one, with three differences:
- Nobody real is contacted. The email goes only to the admin who created the key (subject starting
[Test]); texts are never sent ("sms": "not_sent_test"). - You play the person's part:
POST /v1/test/requests/{id}/simulate-uploaduploads SealDrop's own sample PDF and photo, fills the questionnaire with sample answers and submits — through the real malware scan, so the files become downloadable a minute or two later, and you can test the whole pull loop. - Kept apart and short-lived: test keys see only test requests and live keys never see them; in the app they appear only under the Test (API) filter; they're deleted with their files after 7 days. Up to 100 test requests a day per organization, outside its email limits.
Errors
Every error has the same shape, with a stable code and a requestId to quote if you contact us. Messages never repeat what you sent.
{
"error": {
"code": "invalid_key",
"message": "The key is missing, unknown, revoked or expired.",
"requestId": "Ab3xYz0EIAMEd1Q="
}
}
| Status | Code | Meaning |
|---|---|---|
| 400 | bad_request | The request is malformed or a field is invalid. |
| 400 | key_in_url | An API key was found in the URL. Keys go only in the Authorization header; rotate any key that was put in a URL. |
| 401 | invalid_key | The key is missing, unknown, revoked or expired. |
| 403 | ip_not_allowed | The key can't be used from this IP address (its allowlist). |
| 403 | missing_scope | The key doesn't have the scope this route needs. |
| 403 | api_disabled | The API is turned off for this organization. |
| 403 | organization_suspended | The organization's account is suspended. |
| 403 | organization_closed | The organization's account is closing or closed. |
| 404 | not_found | No such route or resource (or it belongs to another organization). |
| 400 | idempotency_required | This call needs an Idempotency-Key header. |
| 409 | idempotency_mismatch | This Idempotency-Key was already used with a different body. |
| 409 | idempotency_in_progress | A call with this Idempotency-Key is still being handled. Retry in a few seconds. |
| 403 | test_keys_only | Only a test key can do this. |
| 429 | test_daily_limit | The organization sent its test requests for today. |
| 429 | daily_email_limit | The organization reached its daily email limit; the request wasn't sent. |
| 403 | sms_not_enabled | Text messages are not on for this organization. |
| 409 | duplicate_email | A contact with this email already exists; error.contactId is theirs. |
| 409 | duplicate_phone | A contact with this mobile number already exists; error.contactId is theirs. |
| 409 | duplicate_idNumber | A contact with this client ID already exists; error.contactId is theirs. |
| 400 | no_client_id | The organization hasn’t set up a client ID in Settings, so contacts can’t have one. |
| 400 | no_mail | The email address's domain can't receive email. |
| 409 | contact_limit | The organization has as many contacts as its plan allows. |
| 409 | group_exists | A group with this name already exists. |
| 409 | group_limit | The organization has as many groups as it can. |
| 403 | live_keys_only | Group sends reach real people, so only a live key can start one. |
| 403 | not_on_plan | Group sending isn't on the organization's plan. |
| 403 | terms_required | An admin needs to accept the bulk-sending terms in the app first. |
| 403 | list_locked | Group sending is locked after automatic pauses until SealDrop reviews it. |
| 409 | batch_active | Another group send is still in progress. |
| 429 | monthly_list_limit | The send would go past the organization's monthly bulk limit. |
| 409 | nobody | Nobody in the chosen groups can be sent to. |
| 400 | acknowledge_required | This send was paused by a safety stop; resume with acknowledged: true after checking its results. |
| 409 | open_link_limit | The organization has as many open links as its plan allows. |
| 403 | live_access_required | Live keys need SealDrop’s approval first: an admin requests it in Settings → Developers. Test keys work meanwhile. |
| 429 | daily_text_limit | The organization reached its daily text limit; the text wasn't sent. |
| 429 | number_text_limit | This mobile number already got today's texts from the organization; the text wasn't sent. |
| 429 | resend_too_soon | This request was resent less than an hour ago. Wait for Retry-After seconds. |
| 409 | resend_limit | This request was already resent 3 times. Cancel it and send a new request if needed. |
| 429 | rate_limited | Too many requests. Wait for Retry-After seconds. |
| 500 | internal | Something went wrong on our side. Retrying later is safe. |
| 400 | invalid_request | One or more fields are invalid; the message names them (never their values). |
Rate limits
Every answer carries X-RateLimit-Limit and X-RateLimit-Remaining (this key, this minute). Over a limit you get 429 rate_limited with a Retry-After header in seconds. After 20 refused keys in a minute, an IP address waits until the next minute.
| Plan | Keys | Calls per minute (each key) | Calls per day (organization) |
|---|---|---|---|
| Basic | 2 | 60 | 5,000 |
| Premium | 5 | 300 | 50,000 |
| Ultimate | 20 | 600 | 200,000 |
Sending limits
The same for your integration and for the organization's staff in the app, so a bug or a busy button can't flood anyone:
- Emails: the organization's daily email limit (
daily_email_limit). - Texts: at most 5 a day to one mobile number (
number_text_limit, or"sms": "number_limit"when the email still went), and the organization's daily text limit — 100 unless raised (daily_text_limit). Days end at midnight in the organization's time zone. - Resends of one request: at most 3, an hour apart (
429 resend_too_soonwithRetry-After, then409 resend_limit). A new request is always possible. - Use the
Idempotency-Keyon every send: a retry of the same call never sends twice.
Security and privacy
- The API runs in AWS Montréal (ca-central-1), like the rest of SealDrop, over HTTPS with TLS 1.2 or newer only.
- A key always acts for its own organization: the organization comes from the key, never from anything in the request.
- Every call is written to the organization's audit log with the key's name — never the key itself.
- Some things stay in the app, for people only: staff accounts, organization settings, API keys and webhooks themselves, the plan, the bulk-sending terms, opt-in pages and closing the account. A leaked key can't create new keys or redirect notifications, and can't start a group send from a test key.
- There are no CORS headers: keys belong on servers, never in a web page.
- Documents only through 5-minute links to malware-scanned copies; files that failed the scan are never served. Your system confirms each import, and SealDrop deletes its copy straight away — the documents live in one place, your system.
- The events feed and webhooks hold ids and types only — never a name, an address, a file name or an answer — and every webhook is signed.
Versions and changes
Every path starts with /v1. We add fields and routes without a new version, so ignore fields you don't know. Anything that would break an integration gets a new version, announced at least 12 months ahead.
Downloads
- API reference — every route, generated from the API's own schemas.
- openapi.json — OpenAPI 3.1, for code generators and API tools.
- Postman collection — every route, with your key and the address as variables.
- Changelog — what changed, and when.
Questions or early access for your integration: connect@sealdrop.ca.