Docs
Connect a form, send transactional email, or prepare a WhatsApp Business connection. Examples, limits and delivery states in one reference.
Quick start
Use this example to send a form from your existing website to SagePigeon. Create a form in the dashboard and copy the endpoint from its Setup tab.
Replace the example action URL below with that endpoint. Keep the hidden _gotcha field: it helps catch spam. The form can send regular form fields or JSON, without a backend on your website.
<form action="https://api.example.com/f/FORM_ID" method="POST">
<input name="email" type="email" required />
<textarea name="message"></textarea>
<input name="_gotcha" type="text" tabindex="-1" hidden autocomplete="off" />
<button>Send</button>
</form>Submit a test from your website, then check the Inbox to confirm it was stored. An accepted submission does not by itself confirm that its notification email was delivered.
React
Use the React component when your website is built with React. Use the Install command to add @formsage/react, then copy the Component example and replace endpoint with your form’s address.
The SDK handles file upload tickets, errors beside fields, the hidden spam field and repeat clicks on Submit. It uses your form markup, so you keep control of its appearance. The package name remains @formsage/react after the SagePigeon rebrand.
import { FormSageForm } from '@formsage/react'
<FormSageForm
endpoint="https://api.example.com/f/FORM_ID"
successMessage={<p>Thanks, we will be in touch.</p>}
>
<input name="name" />
<input name="email" type="email" required />
<input name="resume" type="file" />
<button>Send</button>
</FormSageForm>npm install @formsage/reactPosting JSON
Use this when your page should submit a form without navigating away. Replace the URL with your form endpoint and pass the visitor’s email and message. A JSON request, or an Accept: application/json header, asks SagePigeon for a JSON response instead of a thank-you page.
await fetch('https://api.example.com/f/FORM_ID', {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ email, message }),
}){
"ok": true,
"submissionId": "SUBMISSION_ID"
}Check the response before showing success. HTTP 200 means the submission was accepted, which includes one held past the month’s allowance on a plan that cannot bill it: it is stored with its answers locked until the workspace upgrades, and the visitor sees nothing different. Missing fields return 422; too many requests return 429; only past ten times the allowance in a month is a submission refused with 402.
Conditional routing
Rules run top to bottom. Every match adds its recipients, a rule marked stop ends evaluation, and if nothing matches the form default is used, so a half-built rule never swallows a lead. Numeric and date comparisons behave the way you would expect. A form can also copy people on every notification with cc, and a rule can add its own cc and bcc when it matches. A cc address appears in the message header; a bcc address does not appear anywhere in it. An address already in To is not copied again, and one message carries at most 50 recipients in all.
When requestType is "Support": support@example.com
When budget is greater than "10000": owner@example.com
When budget is "Over $50k": founders@example.com (stop)POST /api/v1/forms/FORM_ID/route-preview
x-api-key: YOUR_API_KEY
content-type: application/json
{
"data": {
"budget": "12000"
}
}{
"recipients": [
"owner@example.com"
],
"cc": [],
"bcc": [],
"matched": [
"Large bookings"
]
}Form email templates
A small mustache-style syntax, shared with the email API’s templates. Every submitted field is available under values, plus helpers for the whole set. Double braces escape, triple braces do not.
Subject: New submission from {{values.name}}
{{{fieldsHtml}}} <!-- prebuilt table of every field -->
{{{attachmentsHtml}}} <!-- links to uploaded files -->
{{fieldsText}} <!-- plain-text version -->
{{#each fields}}{{label}}: {{value}}
{{/each}}
{{#if values.phone}}Call back on {{values.phone}}{{/if}}
{{submittedAt}} · {{meta.ip}}Replies and delivery
Notifications carry a reply address that routes back into the submission. Answer from your own inbox: the reply is threaded onto the record and forwarded to the person who filled the form in. Bounces and complaints land in the delivery log and suppress the address automatically.
queued 10:04:01
sent 10:04:02 hello@acme.com
delivered 10:04:06 hello@acme.com
reply 10:41:22 hello@acme.com
bounce 10:04:09 old@acme.com, Permanent: 550 5.1.1 user unknownFile uploads
Files never pass through the form endpoint. The browser asks for a ticket, PUTs straight to storage, and posts the returned keys with the submission. Recipients get expiring links; executable file types are always refused.
const ticket = await fetch(endpoint + '/uploads', {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ field: 'resume', filename: file.name, bytes: file.size }),
}).then((r) => r.json())
await fetch(ticket.uploadUrl, { method: 'PUT', body: file })
// then include { _attachments: [{ ...ticket, filename, bytes }] } in the submissionSpam controls
No captcha by default. A honeypot field is on from the first submission, per-IP rate limits apply per minute and per hour, and auto-responses are throttled per destination address so the endpoint cannot be aimed at a stranger. When a form gets noticed, add a challenge in Settings: Cloudflare Turnstile, or reCAPTCHA v3. Turnstile answers pass or fail. v3 returns a score instead, so a token that fails to verify is refused while one that merely scores low is filed as spam for review, real people on VPNs and private browsers score low too, and refusing them outright loses submissions you never hear about.
<input name="_gotcha" type="text" tabindex="-1" hidden autocomplete="off" />
// Turnstile: post the widget's token as cf-turnstile-response
// reCAPTCHA v3: post the token as g-recaptcha-response
grecaptcha.ready(() => {
grecaptcha.execute(SITE_KEY, { action: 'submit' }).then((token) => {
form.querySelector('[name=g-recaptcha-response]').value = token
form.submit()
})
})Webhooks and chat
Forward submissions to Slack, Discord, Teams, or your own endpoint. Verify the signature before trusting the body.
// headers
formsage-timestamp: 1730000000
formsage-signature: sha256=…
const expected = createHmac('sha256', secret)
.update(`${timestamp}.${rawBody}`)
.digest('hex')
// compare with timingSafeEqual, and reject timestamps older than 5 minutesSheets and hooks
Google Sheets appends each submission as a row, adding a column when a form gains a field. To have submissions pushed to Make, n8n or your own service, subscribe its URL with a write API key: each submission is sent as it arrives, not on a polling interval.
POST /api/v1/hooks
x-api-key: YOUR_WRITE_API_KEY
content-type: application/json
{
"targetUrl": "https://hooks.example.com/inbox",
"formId": "FORM_ID"
}{
"id": "HOOK_ID",
"event": "submission.received"
}{
"id": "SUBMISSION_ID",
"form_name": "Website contact form",
"submitted_at": "2026-11-18T09:00:00Z",
"routed_to": "sales@example.com",
"name": "Jo",
"email": "jo@example.com"
}The webhook payload uses a flat object so fields map directly to sheet columns or automation inputs.
- DELETE /api/v1/hooks/:id
- Unsubscribe a hook using its returned id.
WhatsApp API · Setup preview
WhatsApp is in setup preview. Sending is not generally enabled yet. You will need Meta approval, an eligible WhatsApp Business sender and approved message templates before using this endpoint in production.
When onboarding is enabled, an administrator connects the client’s Business Account in client settings. Each client uses its own sender. This connection supports standard Cloud API numbers; keeping the same number active in the WhatsApp Business app is not supported.
Replace the client ID, recipient and template in this example. The parameter values must match your approved template. WhatsApp usage is separate from your email and form allowances.
POST /api/v1/whatsapp/messages
{
"clientId": "YOUR_CLIENT_ID",
"to": "+12025550123",
"template": "approved_reminder",
"parameters": [
"Jo",
"Friday at 10:00"
],
"idempotencyKey": "reminder-booking-8812",
"consentAt": "2026-11-18T09:00:00.000Z"
}{
"messageId": "MESSAGE_ID",
"status": "accepted",
"template": "approved_reminder",
"createdAt": "2026-11-18T09:10:00.000Z"
}Use a write API key. An accepted response does not confirm delivery; check the message status.
Before sending
Use a write API key with access to this client, and keep it on your server. A key pinned to one client can leave out clientId.
Only send to a recipient who has agreed to receive WhatsApp messages from that business. Set consentAt to when you actually recorded that agreement. Do not use the current time to fill in a missing consent record.
The template name and number of parameters must match an enabled, approved template. Customer connections currently import text body templates without media, headers or buttons. Freeform chat and a shared WhatsApp inbox are not available. A 503 not_configured response means the client has no enabled sender.
Delivery status and retries
Save the messageId returned by a send, then use it in the GET request below to check progress. Signed Meta callbacks update the record. An accepted response does not mean the recipient received the message.
If a request times out, keep the same idempotencyKey and payload when checking the original send. A sending or unknown status may mean Meta already accepted it. A new key could send a duplicate. Changing the payload while keeping the key returns 409.
There is no automatic retry queue or fallback to email. The daily cap returns 429. Suppressed recipients and definite provider refusals return 422. STOP and equivalent replies prevent further sends to that recipient for this client.
GET /api/v1/whatsapp/messages/MESSAGE_ID?clientId=YOUR_CLIENT_ID
x-api-key: YOUR_API_KEY{
"messageId": "MESSAGE_ID",
"status": "delivered",
"template": "approved_reminder",
"createdAt": "2026-11-18T09:10:00.000Z"
}Possible states: sending, unknown, accepted, sent, delivered, read and failed.
Email API
Send receipts, reminders and password reset emails from your application. You can send a published template with values to fill in, or provide the subject and body yourself. The Email API is available on Pro and Scale.
In the example, replace Order receipt with your published template name, change the recipient, and supply the values your template uses. Use a different idempotencyKey for each business event, such as one order, and reuse it when retrying that same event.
POST /api/v1/emails
{
"template": "Order receipt",
"to": "customer@example.com",
"variables": {
"customer": {
"name": "Jo"
},
"order": {
"total": "$140.00"
}
},
"idempotencyKey": "order-8812"
}{
"id": "MESSAGE_ID",
"status": "sent",
"scope": "workspace",
"clientId": null,
"to": [
"customer@example.com"
],
"suppressed": [],
"remainingToday": 1999
}Send a write API key in the x-api-key header from your server. The 202 response means accepted for delivery, not delivered to an inbox. Check the Email log for delivery events. Limits: 10 recipients per request and a daily allowance for your plan.
Authentication
An API key lets your server call SagePigeon without signing in for each request. An owner or administrator can create one under Sending → API keys on a paid plan. Enable writes if your application needs to send email.
Use the API key example for your integration. Replace YOUR_API_KEY and the example host with your own values. API-key calls use /api/v1/… and the x-api-key header. Authorization: Bearer fsk_… is also supported on those routes.
Signed-in dashboard calls use /v1/… with an ID token from /auth/login, as shown in the Session example. An API key does not work on that path. Keys cannot manage people, other keys or billing; those actions need a signed-in account.
A key restricted to one client can only act for that client. Keys may update a form’s webhook, captcha and destination settings, but responses hide secrets and show external URLs by host only. Reading and saving a form does not erase those hidden settings. Rotating a signing secret needs a signed-in account.
curl https://api.example.com/api/v1/emails/usage \
-H 'x-api-key: YOUR_API_KEY'curl https://api.example.com/v1/emails/usage \
-H 'authorization: Bearer <ID token from /auth/login>'A read only key cannot send email. A client key cannot send for another client. Both requests return HTTP 403.
Sending a body
Use this example when your application supplies the email wording directly. Change the recipient, subject and body. To send from receipts@acme.com, first verify and select that sending domain, or remove from to use the configured default.
The Request block contains the JSON body to send. The 202 response shows the message ID and remaining daily allowance. Repeat request shows what comes back when the same idempotency key is used again.
POST /api/v1/emails
{
"to": "customer@example.com",
"from": "receipts@acme.com",
"subject": "Your receipt",
"html": "<p>Thanks, your order is confirmed.</p>",
"text": "Thanks, your order is confirmed.",
"replyTo": "support@acme.com",
"idempotencyKey": "order-8812"
}{
"id": "MESSAGE_ID",
"status": "sent",
"scope": "workspace",
"clientId": null,
"to": [
"customer@example.com"
],
"suppressed": [],
"remainingToday": 1999
}{
"id": "MESSAGE_ID",
"status": "sent",
"deduplicated": true
}A repeated idempotency key returns HTTP 200 with the original send. Omit from to use the configured default sender.
- to
- One email address or an array of up to 10 addresses.
- from
- Optional. A custom address must belong to the verified domain selected for this send. Without from, the default is noreply@ that domain. If no domain is selected, the configured shared sender is used.
- subject, html, text
- Provide a subject and email content. If text is omitted, it is derived from html. The subject limit is 200 characters; html and text together are limited to 256 KB.
- replyTo
- Optional. One address or an array of addresses for replies. A client’s saved reply-to address is used when the request omits it.
- idempotencyKey
- Optional, up to 200 characters. Identifies this send so retrying the same event does not create another email.
- clientId
- Identifies the client you are sending for. A key pinned to one client uses that client automatically. A session restricted to clients must name one. Client sends use that client’s sender identity and never borrow the workspace’s sending domain.
Sending with a template
Use a template when someone should be able to update email wording from the dashboard without changing your application code. Publish the template first, then use its name or templateId in the request.
Replace the sample variables with the fields your template needs. templateVersion keeps a send on one published version. Leave it out to use the newest published version. Do not include a separate subject, html or text when sending a template.
Recipient checks, suppression and size limits apply after the template is filled in. An unpublished template cannot be sent.
POST /api/v1/emails
{
"template": "Order receipt",
"to": "customer@example.com",
"variables": {
"customer": {
"name": "Jo"
},
"order": {
"total": "$140.00"
}
},
"idempotencyKey": "order-8812",
"templateVersion": 3
}{
"error": "bad_request",
"message": "No template called \"Receipt v2\""
}An unknown template, unknown version, unpublished template or a request mixing a template with a body returns HTTP 400. See Errors and limits below.
Tracking replies
Set trackReplies to true when you want customer replies stored against the email you sent. SagePigeon supplies a reply address, removes quoted history from incoming replies, saves them on the message and forwards them to your replyTo address. Answering a forwarded message replies directly to the customer.
Tracking is off unless you request it. Check replyTracking.enabled in the response: false means the email was still sent using your normal reply-to address, but the plan or deployment could not capture replies. Each message keeps up to 50 replies.
POST /api/v1/emails
x-api-key: YOUR_API_KEY
content-type: application/json
{
"to": "customer@example.com",
"subject": "Your booking",
"text": "Your booking is confirmed.",
"replyTo": "bookings@acme.com",
"trackReplies": true
}{
"id": "MESSAGE_ID",
"status": "sent",
"replyTracking": {
"enabled": true
}
}{
"replyTracking": {
"enabled": false,
"reason": "Reply tracking is not included in this plan"
}
}When inbound mail is not configured, replyTracking.enabled is also false and the reason explains that replies cannot come back to this deployment.
- GET /api/v1/emails?replied=yes
- Lists emails with replies. Use replied=no for emails without replies; any other value returns 400. Each item includes trackReplies, replyCount and lastReplyAt.
- GET /api/v1/emails/:createdAt/:emailId
- Returns the message and its replies, oldest first. Each reply includes id, createdAt, from, subject and text.
Templates
Templates belong to the workspace and are quoted by name, so a name is unique ignoring case (409 on a clash). Reading them takes any signed-in session or key that can see workspace-owned things, a session limited to particular clients or forms gets an empty list and 404s. Creating, publishing, renaming, restoring and deleting need the admin role and a signed-in account; an API key is refused with 403. Every publish is a version; a restore republishes an older version as a new one that records where it came from; a rename on its own is not a version. Limits: name 80 characters, subject 200, body 256 KB. The variables list is read from the words at publish time and is advisory. A send that omits one renders it empty rather than failing.
POST /v1/templates
Authorization: Bearer <ID token from /auth/login>
content-type: application/json
{
"name": "Order receipt"
}{
"template": {
"templateId": "TEMPLATE_ID",
"name": "Order receipt",
"version": 0
}
}{
"error": "conflict",
"message": "A template called \"Order receipt\" already exists"
}Version 0 is a draft. Publish it with PUT before sending from it. Reading uses /api/v1 with a key; creating, changing and deleting require a signed-in administrator on /v1.
- GET /api/v1/templates
- Returns templates with templateId, name, version, variables, subject, html, text, updatedAt and updatedBy.
- GET /api/v1/templates/:templateId
- Returns one template.
- PUT /v1/templates/:templateId
- Publish subject, html, optional text and summary as a new version. Send name alone to rename without creating a version. Send restore with a version number to republish that version as a new one.
- GET /api/v1/templates/:templateId/versions
- Returns versions with summary, publishedAt, publishedBy, optional restoredFrom, variables, subject, html and text.
- POST /api/v1/templates/preview
- A write key can preview subject, html and optional text. The response lists the variables these words need.
- DELETE /v1/templates/:templateId
- Deletes a template and returns 204. Requires a signed-in administrator.
The log and your allowance
What was sent through the API and what became of it, scoped like every other list. A key limited to a client sees that client’s sends. Delivery, bounce and complaint events from the mail provider are added to each message as they arrive. Every list endpoint takes an optional window as from and to, both inclusive: a date (YYYY-MM-DD, read as that whole UTC day) or an ISO 8601 time with its offset. The usage endpoint says what is left today, so a client can pace itself: a new workspace sends 50 a day, then 200 after three days and 1,000 after seven, before reaching its plan’s cap two weeks in (Pro 2,000 a day, Scale 20,000; the free plan has no email API).
GET /api/v1/emails/usage
x-api-key: YOUR_API_KEY{
"sentToday": 1,
"dailyLimit": 2000,
"planLimit": 2000,
"warmingUp": false,
"remainingToday": 1999,
"window": {
"sent": 1240,
"bounced": 9,
"complained": 1
},
"sendingDomain": "acme.com"
}- GET /api/v1/emails?limit=50&cursor=CURSOR
- Lists messages and returns the next cursor. Items include emailId, to, from, subject, createdAt, status, messageId, error, events, clientId, trackReplies, replyCount and lastReplyAt.
- from, to
- Filter the list using either or both dates, for example from=2026-09-01&to=2026-09-30T23:59:59Z.
- replied=yes or replied=no
- Filter by whether a reply has arrived.
- GET /api/v1/emails/:createdAt/:emailId
- Returns one message with its delivery events and replies.
- blocked
- When sending is refused, usage also includes a blocked object with the code and message explaining why.
Errors and limits
When a request fails, read its error code and message before trying again. Fix the reason listed below. A 429 response includes a retry-after header telling you when you can try again; retrying immediately will not help. Only the first failing check is reported, so another issue may appear after you correct it.
- 400 bad_request
- no recipient; more than 10; an invalid address; no subject or body; a template with a body; an unknown template or version
- 403 forbidden
- read-only key; key pinned to another client; a scoped session sending workspace-owned mail without "clientId"
- 403 plan
- the email API is on the paid plans
- 403 no_verified_domain
- "from" was given, and no domain is verified and chosen for this send
- 403 sender_not_allowed
- "from" is not on the domain this send uses
- 403 bounce_rate
- ≥ 4% of the last 30 days bounced (once 50 have been sent), sending paused
- 403 complaint_rate
- ≥ 0.1% marked as spam, sending paused
- 403 suspended
- sending suspended for this workspace by the operator
- 422 suppressed
- every recipient is on your suppression list (the send is logged as such)
- 429 rate_limited
- more than 60 a minute or 1,000 an hour; or the daily cap, which resets at midnight UTC
- 502 send_failed
- the mail provider refused the message (the quota is given back)
- 503 service_paused
- the email API is paused across the deployment; try again shortly
formsage.js
One script, no dependencies, no build step. It takes over any form marked data-formsage (or whose action is a SagePigeon endpoint) and submits it in place with fetch, so the page stays where it is. A plain HTML form keeps working exactly as before without it, the script is for pages that want to stay put, show their own messages, or know when a submission failed before it ever reached SagePigeon.
<script src="https://app.example.com/formsage.js" defer></script>
<form action="https://api.example.com/f/FORM_ID" method="POST" data-formsage>
<input name="email" type="email" required />
<textarea name="message"></textarea>
<input name="_gotcha" type="text" tabindex="-1" hidden autocomplete="off" />
<button>Send</button>
</form>
<!-- Or submit a form yourself: -->
<script>
FormSage.submit(document.querySelector('form'))
.then((result) => console.log(result.kind, result.status))
</script>Events
The form dispatches three CustomEvents. formsage:submit fires before the request and can be cancelled with preventDefault() to take over. formsage:success and formsage:error carry { kind, status, code, message } in detail; calling preventDefault() on either stops the default behaviour, on success, following the form's redirect when it has one and otherwise replacing the form with a thank-you (data-formsage-success sets the words); on error, an inline message with role="alert".
form.addEventListener('formsage:success', (e) => {
e.preventDefault() // keep the form; show your own thanks
console.log(e.detail.status) // 200
})
form.addEventListener('formsage:error', (e) => {
e.preventDefault()
// e.detail.kind: "refused" | "network" | "timeout" | "blocked" | "script"
// e.detail.code: the endpoint's error, e.g. "origin_not_allowed", or the kind
// e.detail.message: a sentence you can show
})What is reported
If a submission fails before reaching SagePigeon, the script sends a short failure report to the form endpoint. It appears on the form’s Health tab as Failed in the browser. Causes include a dropped connection, a timeout after 15 seconds, a browser security restriction or a script error. The report contains the failure type and page path, never field values or the visitor’s address. Requests SagePigeon itself refuses are already counted by the endpoint. A plain HTML form still submits without the script, but cannot report browser failures.
POST /f/FORM_ID/client-errors
{ "reports": [{ "kind": "network", "page": "/contact" }] }Management API
The dashboard talks to the same REST API you can script against. With an API key in x-api-key, call it under /api/v1, as listed here. Signed in with the ID token from /auth/login, call the same routes under /v1 (see Authentication). People, keys and billing are signed-in only.
POST /auth/login
content-type: application/json
{
"email": "you@example.com",
"password": "YOUR_PASSWORD"
}{
"idToken": "ID_TOKEN",
"refreshToken": "REFRESH_TOKEN"
}- GET /api/v1/forms
- List forms.
- POST /api/v1/forms
- Create a form with preset, name, recipients, cc and bcc.
- PATCH /api/v1/forms/:id
- Update settings including routingRules, destinations, uploads, cc and bcc.
- POST /api/v1/forms/:id/test
- Send a notification test with kind set to notification.
- POST /api/v1/forms/:id/test-submission
- Store a marked test submission. Requires writes; notifies team recipients only and sends no auto-reply.
- GET /api/v1/forms/:id/submissions
- List submissions. Supports q for search and cursor for pagination.
- GET /api/v1/forms/:id/export
- Export CSV.
- DELETE /api/v1/forms/:id/submissions/:createdAt/:submissionId
- Delete a submission.
- GET /api/v1/privacy/search?email=ADDRESS
- Find data for one address. See Subject access and erasure below.
- DELETE /api/v1/privacy/erase?email=ADDRESS
- Erase matching submission data. See the scope and limits below.
- GET /api/v1/analytics?days=30
- Read analytics.
- GET /api/v1/domains; POST /api/v1/domains/:domain/verify
- List sending domains or check verification.
- GET /api/v1/suppression
- Read suppressed addresses.
- POST /api/v1/emails
- Send with template, variables and to. An accepted request returns 202.
- GET /api/v1/templates
- Read templates.
- Signed-in account: people and keys
- GET /v1/team, POST /v1/team/invites, GET /v1/keys and POST /v1/keys require the ID token.
- Signed-in account: billing
- GET /v1/billing. POST /v1/billing/checkout with plan and period starts a subscription; POST /v1/billing/change changes an existing paid subscription.
- PUT /v1/templates/:id
- Change a template using a signed-in administrator account.
Subject access and erasure
Find or delete every submission that mentions one email address, across every form you can see. The address is matched whole and without regard to case: a field that is the address, or that holds it next to a space, comma, semicolon, angle bracket, bracket, colon or quote, as in "Jo <jo@example.com>". Erasing jo@example.com never touches bojo@example.com or jo@example.com.au, and anything that is not one email address is refused with a 400. Spam held for review is included. A large workspace may take more than one call: when "complete" is false, call again with the "cursor" it returned. Each erasure is recorded in the activity log with a fingerprint of the address, never the address itself. Both calls need a key or account that can write (a read-only key or a client login is refused with a 403), and together they are limited to 30 calls a minute per workspace (429 after that). The email log, file links already sent and any copies outside SagePigeon are not covered by this call.
GET /api/v1/privacy/search?email=jo@example.com
x-api-key: YOUR_WRITE_API_KEY{
"email": "jo@example.com",
"count": 2,
"complete": true
}DELETE /api/v1/privacy/erase?email=jo@example.com
x-api-key: YOUR_WRITE_API_KEY{
"erased": 2,
"failed": 0,
"complete": true
}{
"erased": 412,
"failed": 0,
"complete": false,
"cursor": "NEXT_CURSOR",
"message": "Not every submission has been checked yet. Call again with this cursor to continue."
}{
"erased": 3,
"failed": 1,
"complete": true
}{
"error": "bad_request",
"message": "Pass ?email= with one email address, such as jo@example.com"
}Search also returns matching submissions. When complete is false, call again with cursor, for example DELETE /api/v1/privacy/erase?email=jo@example.com&cursor=NEXT_CURSOR. Retry failed deletions; if none could be deleted, the response is 500.
MCP server
An AI assistant that speaks MCP can read your forms and submissions through SagePigeon, and with the right key build and publish forms. The endpoint is /api/v1/mcp on the same host as the rest of the API, and it takes an API key as Authorization: Bearer fsk_… (a request with x-api-key is refused there, and so is a key in the URL). Pro and Scale only, the same as API keys. What the assistant can do depends on the key: a read-only key gets the 11 read tools, a key created with writes gets 5 more. Make a read-only key to start. Make a second one with writes for the session where you want a form built, and revoke it after. Both are made under Sending → API keys.
claude mcp add --transport http formsage https://api.example.com/api/v1/mcp \
--header "Authorization: Bearer fsk_live_…"After adding the server, open /mcp in Claude Code to check the connection. A wrong key returns 401.
Other clients
Cursor reads remote servers from ~/.cursor/mcp.json, or .cursor/mcp.json in one project. It can read the key from an environment variable, so the file need not hold it. Claude custom connectors (claude.ai and the desktop app) have a Request headers section for a fixed credential: set Authentication to No sign-in, add an authorization header, and enter the whole value including the word Bearer, because Claude sends it exactly as typed. Anthropic describes that section as a beta open to a limited set of organizations, so it may not be in your dialog yet; if it is not, SagePigeon cannot be added there, because the server takes an API key and does not offer OAuth. Any other client that can send an Authorization header to a remote Streamable HTTP server can use the same URL and header.
{
"mcpServers": {
"formsage": {
"url": "https://api.example.com/api/v1/mcp",
"headers": {
"Authorization": "Bearer ${env:FORMSAGE_API_KEY}"
}
}
}
}MCP server URL: https://api.example.com/api/v1/mcp
Authentication: No sign-in
Request header: authorization = Bearer YOUR_API_KEYTools
Sixteen tools. Lists are short on purpose: at most 25 submissions or messages and 100 forms a call, with long values cut, and get_submission returns one in full. A list row shows the first six fields of a submission, or the ones the assistant names. create_form makes a live form. Changes to an existing form are saved as a draft and the live form stays as it was until publish_form_draft. Both take cc and bcc addresses (up to 10 each) for every notification, and routing rules, each with conditions on a field’s value, up to 10 recipients, its own cc and bcc, an optional email of its own and a stop flag, and upload settings (file types, size, file count) for a file field such as a résumé on a job application. A new list of rules replaces the old one, including rules a client added, and files go up to 10 MB each on Pro and 25 MB on Scale. get_form shows both. The assistant never gets a file or a link to one. send_test_submission stores a submission marked as a test, emails the form’s recipients, including those a routing rule picks, who are on your workspace’s team (anyone else is skipped, and a form with none is refused) with [test] in the subject, and runs the form’s webhooks, REST hooks and chat destinations as a real one would; it sends no auto-reply, does not count toward your monthly submissions, and is limited to 2 a minute and 10 an hour for the whole workspace. Webhook and destination URLs, secrets and captcha keys are never returned; REST hooks are listed by host only.
Read tools (any key)
get_account workspace, plan, whether this key can write, clients it can act for, usage
list_presets starting points for a new form
list_forms forms with endpoint and hosted page address
get_form one form's settings, and its unpublished draft if asked
get_embed_code HTML and formsage.js snippets built from the live fields
get_form_health recent refusals, browser failures and bounced deliveries, with advice
get_analytics submissions, spam and delivery per day and per form
list_submissions newest first, values shortened
get_submission one submission in full, with its replies
list_messages the email log, or one submission's whole conversation (cc shown, bcc never)
list_webhooks REST hooks, by host only
Write tools (key with writes)
create_form a live form from a preset or a list of fields, with routing rules, cc and bcc, and uploads
save_form_draft changes to an existing form, rules, cc, bcc and uploads included, held as a draft
publish_form_draft makes the draft live; refused if the form changed meanwhile
send_test_submission one marked test submission through the live form
create_webhook subscribe an https URL to new submissionsWhat it will not do
There is no tool that deletes anything, replies to or emails a submitter, releases spam, or touches billing, people, keys, invites, clients or domains. Chat destinations, a form’s own webhook URL and its secrets stay in the dashboard. Every tool runs through the same checks as the REST API, so a key limited to one client reaches only that client’s forms. Submitted values, replies and subjects are written by people outside your workspace; each result that carries them says so, but an assistant that reads them can still be misled, which is a good reason to keep the key read-only unless it is building something. A revoked key stops working on its next request. Each write is recorded in the activity log against the key.
forbidden: This API key is read-only{
"jsonrpc": "2.0",
"id": null,
"error": {
"code": -32003,
"message": "PLAN_ERROR_MESSAGE"
}
}{
"jsonrpc": "2.0",
"id": null,
"error": {
"code": -32600,
"message": "The MCP endpoint takes no query string"
}
}