Labeling with Clef

Labels organise mail for humans (filters, chips) and machines (webhook filters, label query parameter, MCP).

How a label is decided

Every incoming email goes through the queue:

1. Rules first. Each label can carry regex rules for sender, subject and body (any or all must match). A matching rule applies the label instantly and for free.
2. Clef for the rest. If Clef is active for the workspace, all labels that have an instruction and were not decided by rules are answered in one Clef call per email.
3. A label is applied when Clef’s probability is at least the label’s threshold (default 70 %). The confidence is stored and shown on the chip.
4. Manual labels win. Labels you set in the dashboard, API or MCP are never overwritten by automation.

What is Clef?

Clef is Cloudflare’s open decision model on Workers AI. Instead of generating text it returns calibrated probabilities for typed questions. Squadmail sends:

await env.AI.run('@cf/cloudflare/clef-flash', {
	model: 'clef-flash',
	state: 'From: …\nSubject: …\n\n…body (trimmed)…',
	questions: {
		spam: {
			type: 'score',
			instructions: 'Is this unsolicited bulk mail…?',
			criteria: ['Clean', 'Suspicious', 'Likely spam', 'Spam']
		},
		receipt: { type: 'noul', instructions: 'Is this an invoice, receipt…?' },
		job_application: { type: 'noul', instructions: 'Is this a job application or CV?' }
	}
});

noul answers become the label confidence; for the built-in spam score Squadmail uses the probability mass on Likely spam + Spam.

Enabling Clef

Clef runs on every received email whenever the AI binding exists. It is cheap — clef-flash, bodies trimmed to 2,000 characters, one call per email for all labels — so it is on by default on self-hosted instances and on every Squadmail Cloud plan.

• CLEF_ENABLED=false turns it off instance-wide (rule-based labels keep working).
• Workspace owners can pause Clef for their workspace on the Labels page.

Cost controls

Variable	Purpose
LABEL_MODEL	clef-flash (default, 9B, fast) or clef (27B, most precise)
LABEL_CALLS_PER_DAY	Per-workspace daily cap
LABEL_GLOBAL_DAILY_BUDGET	Instance-wide kill switch
AI_GATEWAY_ID	Route calls through AI Gateway for caching, analytics and rate limiting

The email body sent to Clef is trimmed to about 6 000 characters (roughly 2k tokens). When a budget is exhausted, labeling is skipped and logged — mail delivery is never blocked.

Writing good instructions

• Ask one yes/no question: “Is this a job application or CV?”
• Be specific about edge cases: “Is the customer blocked from using the product (not just asking a question)?”
• Use rules for things regex can decide (from: @github\.com$).
• Tune the threshold in the playground on the Labels page — it shows each label’s confidence for a sample email without storing anything.

API

# dry run
curl -X POST https://app.squadmail.dev/api/v1/labels/test -H "Authorization: Bearer $KEY" 
  -H "content-type: application/json" 
  -d '{"from":"jobs@greenhouse.io","subject":"New application","text":"Please find my CV attached"}'

# filter emails by label
curl "https://app.squadmail.dev/api/v1/emails?label=verification" -H "Authorization: Bearer $KEY"