Documentation

Everything you need to build powerful AI workflows.

Getting started

Ferio turns your inbox into a programmable AI assistant. Three steps to your first Spark:

Connect Google — go to Settings and authorize Gmail and Drive access.
Add your Anthropic API key — get one at console.anthropic.com. We encrypt it at rest and never share it.
Create a workflow — use a template or start from scratch.

💡 Tip: Hit "Test run" on any workflow to fire it with mock data — no need to wait for a real email.

Core concepts

Workflow: A blueprint: trigger + AI prompt + one or more actions.
Trigger: What starts the workflow — a new email, a new attachment, a schedule.
AI prompt: Plain-English instructions Claude follows when the trigger fires.
Action: What happens after the AI: save to Drive, send a reply, apply a label.
Spark: One full workflow run. The unit we charge for. 1 Spark = 1 run, regardless of step count.

Triggers

Today, Ferio supports five trigger types:

New email received — fires on every new email matching your filters.
New email with attachment — narrower, only emails containing files.
Email gets a label — fires when you (or a Gmail filter) apply a specific label to an email. Common pattern: "When I label X as 'Process', do Y." Polled every 5 minutes; only fires for emails newer than the workflow's last update to avoid back-fill floods.
Webhook — POST any JSON to a unique URL to fire the workflow. Great for connecting external apps, GitHub, Zapier, n8n, etc.
Schedule — run a workflow on a recurring interval (5min – 7 days).

Filters

You can narrow which emails trigger a workflow:

From — match part of the sender's email (e.g. invoices@acme.com or just acme.com).
Subject contains — case-insensitive substring match.
Has attachment — only fire when there's at least one file.

💡 Tip: Polling runs every 5 minutes and only processes unread emails. Once a Spark fires, the email is marked as read.

Writing AI prompts

Your AI prompt tells Claude what to do with each email. Keep it specific.

Bad prompt

Process this email

Good prompt

Extract the invoice number, vendor name, and total amount from this email.
Format the output as JSON with keys: invoice_number, vendor, total.
If any field is missing, use null.

Claude automatically receives the email's from, to, subject, date, and body as context — you don't need to mention these.

💡 Tip: For reply actions, write your prompt in the voice you want Claude to use. The output goes directly into the reply body.

Actions

Save attachment to Drive: Saves email attachments to a Drive folder. Pick from your folder list or paste a folder ID.
Save AI output to Drive: Writes Claude's response as a new file (Markdown / plain text / CSV / JSON) into a folder. The folder is created if it doesn't exist. Filename supports {{...}} placeholders for dynamic naming.
Apply Gmail label: Tags the email with a label. Auto-creates the label if it doesn't exist.
Send Gmail reply: Replies to the email's thread with Claude's output as the body.
Send webhook: POSTs Claude's output + trigger data to any URL you specify. Use this to integrate with anything.

More integrations coming: Slack messages, Notion pages, Google Calendar.

Variables in action params

Action params support placeholders that get resolved at runtime:

{{trigger.subject}} — the email subject (or any field from the trigger)
{{trigger.from}} — the sender's email
{{ai}} — Claude's full output

Example label: Invoices/{{trigger.from}} dynamically organizes by sender.

Testing workflows

Open any workflow and click the ▶ Test run button (top right). This fires a Spark immediately with mock email data, so you can:

Verify your AI prompt is producing the right output
Make sure your Drive folder ID is valid
Catch errors before real emails start arriving

Test Sparks count toward your monthly limit. They appear in your Sparks history just like real ones.

Billing & limits

Free plan

100 Sparks per calendar month
3 workflows max
7-day spark history

Starter — $15/mo

2,000 Sparks per month
Unlimited workflows
90-day spark history
$0.01 per Spark over the limit

Counts reset on the 1st of each month at 00:00 UTC. We email you when you hit 80% and 100%.

API access

You can manage workflows and Sparks programmatically with API tokens. Create a token from Settings → API tokens.

Authentication

Send your token as a Bearer header:

Authorization: Bearer ign_<your-token>

Example: list workflows

curl https://api.sparkferio.com/api/workflows \
  -H "Authorization: Bearer ign_xxx"

Example: trigger a webhook workflow

If you have a webhook-triggered workflow, you can also POST directly to its public URL (no auth needed beyond the secret in the URL):

curl https://api.sparkferio.com/webhooks/trigger/<webhook-secret> \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"any":"data"}'

Available endpoints

GET /api/workflows — list workflows
POST /api/workflows — create workflow
GET /api/workflows/:id — get workflow
PATCH /api/workflows/:id — update workflow
DELETE /api/workflows/:id — delete workflow
POST /api/workflows/:id/test — fire test Spark
GET /api/sparks — list Sparks
POST /api/sparks/:id/retry — retry a failed Spark

Troubleshooting

Q: My workflow isn't firing

Check that: (1) the workflow status is Active, (2) your Google account is connected (Settings), and (3) the trigger filters actually match your emails. Polling happens every 5 minutes.

Q: Spark failed with 'No Anthropic API key set'

Add your key in Settings → Anthropic API key. Get one at console.anthropic.com.

Q: Spark failed with 'Spark limit reached'

You've used all your Sparks for this month. Upgrade to Starter or wait for the monthly reset.

Q: Drive save failed — 'File not found'

Double-check the folder ID. It's the long string after /folders/ in the Drive URL. Make sure your Google account has write access to it.

Q: My Gmail reply was sent but looks weird

Refine your AI prompt — it's the voice Claude uses. Use phrases like "Write a brief, friendly reply" or "Keep it under 4 sentences".

Need more help? Email hello@sparkferio.com.