Followkite API

A JSON REST API at https://followkite.com/api/v1. It does what the app does, with the same validation, plan limits, do-not-contact rules and activity log, so nothing you send through it can bypass the safety controls.

Authentication and keys

Create a key in Integrations → API keys. Send it as Authorization: Bearer fk_live_…. A key belongs to one workspace and acts with the role of the person who created it, narrowed to its scopes. If that person leaves the workspace, the key stops working. Browser cookies are never accepted on /api/v1.

Errors and limits

Errors are JSON: {"error": "invalid_input", "field": "…"}. Common codes: invalid_api_key (401), insufficient_scope (403, with required), ip_not_allowed (403), plan_limit_… (403), rate_limited (429). Each key may make 120 requests a minute; see the X-RateLimit-* headers.

Endpoints

const res = await fetch('https://followkite.com/api/v1/contacts', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.FOLLOWKITE_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ email: 'ann@clinic.com', firstName: 'Ann', company: 'Bright Smiles', listIds: ['…'] }),
});
if (res.status === 429) await new Promise((r) => setTimeout(r, Number(res.headers.get('retry-after')) * 1000));

Transactional email

Send receipts, password resets and alerts from your app. Set up your sending domain under Transactional email → Settings (or connect your own Amazon SES or SMTP relay there), and send from a domain you have verified on the Domains page.

curl https://followkite.com/api/v1/send \
  -H "Authorization: Bearer fk_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-receipt" \
  -d '{
    "from": "Shop <orders@yourdomain.com>",
    "to": "ann@example.com",
    "template": "order-receipt",
    "data": { "name": "Ann", "order": { "id": "1042" }, "items": [{ "title": "Cap", "qty": 2 }] },
    "tags": ["receipt"],
    "metadata": { "orderId": "1042" }
  }'

HTTP/1.1 202 Accepted
{ "id": "7c1e…", "status": "SENT", "to": "ann@example.com", "subject": "Receipt #1042",
  "tags": ["receipt"], "metadata": { "orderId": "1042" }, "template": { "id": "…", "version": 3 }, "duplicate": false }

Fields

• from: "Name <address>" or { email, name }; defaults to the workspace's default sender.
• to, replyTo: one address each.
• subject + html and/or text, or template (slug or id) + optional version and data. Plain text is generated from the HTML when missing.
• headers: up to 20 X- headers (also List-Unsubscribe, List-Id). tags: up to 10. metadata: up to 20 keys; both are echoed in webhooks.
• sendAt: ISO time up to 30 days ahead; cancel with POST /messages/{id}/cancel.
• sandbox: true: checks and renders without delivering. track: { opens, clicks }: optional tracking.

Batch: POST /send/batch takes the same fields plus recipients: [{ to, data, tags, metadata }] (up to 1,000). Each recipient is checked on its own; the response lists accepted and rejected rows. Batches go out from the queue within a minute; single sends are attempted at once.

Templates

Hi {{name|there}},                       variable with a fallback
Order {{order.id}}                        nested fields
{{#if paid}}Paid{{else}}Due{{/if}}        conditionals ({{#unless}} too)
{{#each items}}{{this.title}} × {{this.qty}}{{/each}}   loops; {{@index}} is the position
{{{raw_html}}}                            not escaped (HTML only)

Every save is a new version; restore an old one from the editor. Set text direction to right-to-left for Arabic or Urdu.

Statuses

SCHEDULED, QUEUED, SENT (accepted by your provider), DELIVERED (SES confirmed), DEFERRED (retrying), BOUNCED, COMPLAINED, DROPPED (address suppressed), FAILED, CANCELLED, SANDBOX. A send whose outcome is unknown is marked FAILED with DELIVERY_UNCERTAIN and never retried, so nobody gets two password resets.

Limits and safety

Your plan sets a monthly allowance. In a workspace's first week, transactional email is limited to 200 a day. Sending pauses automatically when bounces reach 5% or spam complaints 0.1% over 100 or more emails in 7 days. Hard bounces and complaints are added to the do-not-contact list.

Webhooks

Add an endpoint in Integrations. Each event is an HTTPS POST signed with X-Followkite-Signature: t=…,v1=… (HMAC-SHA256 of t.body with your signing secret). Failed deliveries are retried with backoff. Events: reply.received, lead.interested, contact.unsubscribed, contact.bounced, campaign.completed, and for transactional email email.sent, email.delivered, email.deferred, email.bounced, email.complained, email.dropped, email.failed, email.opened, email.clicked. Slack alerts for interested leads are set up separately in Integrations.

Questions

Last updated 13 October 2026.