On this page

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.

HTML
<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.

Component
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>
Install
npm install @formsage/react

Posting 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.

Request
await fetch('https://api.example.com/f/FORM_ID', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ email, message }),
})
200 response
{
  "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.

Example rules
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)
Request: preview routing
POST /api/v1/forms/FORM_ID/route-preview
x-api-key: YOUR_API_KEY
content-type: application/json

{
  "data": {
    "budget": "12000"
  }
}
Response
{
  "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.

Example
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.

Example
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 unknown

File 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.

JavaScript
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 submission

Spam 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.

HTML
<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.

JavaScript
// 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 minutes

Sheets 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.

Request: subscribe
POST /api/v1/hooks
x-api-key: YOUR_WRITE_API_KEY
content-type: application/json

{
  "targetUrl": "https://hooks.example.com/inbox",
  "formId": "FORM_ID"
}
Response
{
  "id": "HOOK_ID",
  "event": "submission.received"
}
Webhook payload example
{
  "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

Request
{
  "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"
}
202 response
{
  "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.

Request
GET /api/v1/whatsapp/messages/MESSAGE_ID?clientId=YOUR_CLIENT_ID
x-api-key: YOUR_API_KEY
200 response
{
  "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

Request
{
  "template": "Order receipt",
  "to": "customer@example.com",
  "variables": {
    "customer": {
      "name": "Jo"
    },
    "order": {
      "total": "$140.00"
    }
  },
  "idempotencyKey": "order-8812"
}
202 response
{
  "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.

API key
curl https://api.example.com/api/v1/emails/usage \
  -H 'x-api-key: YOUR_API_KEY'
Session
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

Request
{
  "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"
}
202 response
{
  "id": "MESSAGE_ID",
  "status": "sent",
  "scope": "workspace",
  "clientId": null,
  "to": [
    "customer@example.com"
  ],
  "suppressed": [],
  "remainingToday": 1999
}
200 response: repeat request
{
  "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

Request
{
  "template": "Order receipt",
  "to": "customer@example.com",
  "variables": {
    "customer": {
      "name": "Jo"
    },
    "order": {
      "total": "$140.00"
    }
  },
  "idempotencyKey": "order-8812",
  "templateVersion": 3
}
400 response
{
  "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.

Request: track 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
}
202 response: tracking enabled (excerpt)
{
  "id": "MESSAGE_ID",
  "status": "sent",
  "replyTracking": {
    "enabled": true
  }
}
202 response: tracking unavailable (excerpt)
{
  "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.

Request: create a template
POST /v1/templates
Authorization: Bearer <ID token from /auth/login>
content-type: application/json

{
  "name": "Order receipt"
}
201 response (excerpt)
{
  "template": {
    "templateId": "TEMPLATE_ID",
    "name": "Order receipt",
    "version": 0
  }
}
409 response: name already used
{
  "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).

Request: daily allowance
GET /api/v1/emails/usage
x-api-key: YOUR_API_KEY
200 response (excerpt)
{
  "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.

HTML
<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".

Example
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.

HTTP
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.

Request: sign in
POST /auth/login
content-type: application/json

{
  "email": "you@example.com",
  "password": "YOUR_PASSWORD"
}
Response (excerpt)
{
  "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.

Request: find matching submissions
GET /api/v1/privacy/search?email=jo@example.com
x-api-key: YOUR_WRITE_API_KEY
200 response (excerpt)
{
  "email": "jo@example.com",
  "count": 2,
  "complete": true
}
Request: erase matching submissions
DELETE /api/v1/privacy/erase?email=jo@example.com
x-api-key: YOUR_WRITE_API_KEY
200 response: erasure complete
{
  "erased": 2,
  "failed": 0,
  "complete": true
}
202 response: more work remains
{
  "erased": 412,
  "failed": 0,
  "complete": false,
  "cursor": "NEXT_CURSOR",
  "message": "Not every submission has been checked yet. Call again with this cursor to continue."
}
207 response: some deletions failed (excerpt)
{
  "erased": 3,
  "failed": 1,
  "complete": true
}
400 response: invalid address
{
  "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.

Shell
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.

Cursor: .cursor/mcp.json
{
  "mcpServers": {
    "formsage": {
      "url": "https://api.example.com/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${env:FORMSAGE_API_KEY}"
      }
    }
  }
}
Claude custom connector settings
MCP server URL: https://api.example.com/api/v1/mcp
Authentication: No sign-in
Request header: authorization = Bearer YOUR_API_KEY

Tools

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.

Example
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 submissions

What 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.

Read only key: tool error
forbidden: This API key is read-only
403 response: plan restriction (outline)
{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32003,
    "message": "PLAN_ERROR_MESSAGE"
  }
}
400 response: query string refused
{
  "jsonrpc": "2.0",
  "id": null,
  "error": {
    "code": -32600,
    "message": "The MCP endpoint takes no query string"
  }
}