Spam

8 operations. Call each with POST https://app.chirply.io/api/v1/actions/<name> and a bearer token; the response is { "data": { "action", "summary", "result" } }. A read badge means the operation changes nothing; write requires the credential’s write scope.

Block a sender

spam.block_senderwriteconfirm

Add one email address, email domain or phone number to this account's blocked-sender list. Anything that arrives from it afterwards is recorded but filed as spam immediately: nobody is notified, it is not forwarded to the account's own mailbox, and no autoresponder or AI agent replies to it. Nothing already in the inbox moves, and nothing is sent or deleted. A `domain` entry covers every mailbox at that domain AND every subdomain under it, so it is the blunt instrument — use `email` unless the sender keeps changing mailbox. Blocking an address a real customer also writes from makes their mail disappear with no bounce and no warning, so confirm the value before calling this.

Marked confirm: this operation is irreversible, reaches real people, or spends money. Holding a credential is itself the confirmation for API and MCP callers — call it only when you mean it. The in-app assistant refuses to run it without a human approving first.

Parameters

Field	Type	Required	Description
kind	"email" \| "domain" \| "phone"	required	What is being blocked: `email` for one mailbox, `domain` for every mailbox at a domain and its subdomains (for a sender who keeps changing address), `phone` for one number however it is punctuated.
value	string	required	The address, domain or number to block. Normalized before it is stored — an address is lower-cased, a domain may be given with or without its @, and a phone number is matched on its digits however it was punctuated.
reason	string	optional	Why, in a few words — shown beside the entry on the Spam screen so the next person understands the decision. Optional, and never shown to the person being blocked.

Example

curl -X POST https://app.chirply.io/api/v1/actions/spam.block_sender \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "email",
    "value": "example"
  }'

Test with your API key

Over MCP the same operation is the tool spam_block_sender at https://app.chirply.io/api/mcp, same bearer token, same input.

Automatic spam detection

spam.get_auto_detectionread

Read this account's automatic spam detection setting (Settings → Spam & blocked senders): whether every inbound email from a stranger is checked by the account's own AI connection, whether a spam verdict also marks the sender as a spammer, and whether cold sales pitches count as spam. Also reports whether AI is connected (without it nothing is checked) and how many people it has marked in the last 30 days. Read-only; sends nothing and costs nothing.

Parameters

No parameters — POST an empty body.

Example

curl -X POST https://app.chirply.io/api/v1/actions/spam.get_auto_detection \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{}'

Test with your API key

Over MCP the same operation is the tool spam_get_auto_detection at https://app.chirply.io/api/mcp, same bearer token, same input.

People marked as spammers

spam.list_marked_contactsread

Read the contacts marked as spammers in this account, newest first, with who they are, when they were marked and the reason given. These contacts are blocked and hidden from normal CRM and inbox views, and their messages and calls sit in spam. Read-only.

Parameters

Field	Type	Required	Description
limit	integer	optional	How many people to return, most recently marked first. Up to 200. Default: 50

Example

curl -X POST https://app.chirply.io/api/v1/actions/spam.list_marked_contacts \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "limit": 50
  }'

Test with your API key

Over MCP the same operation is the tool spam_list_marked_contacts at https://app.chirply.io/api/mcp, same bearer token, same input.

Blocked senders

spam.list_sendersread

Read this account's blocked-sender list: every email address, email domain and phone number whose messages are filed as spam the moment they arrive, with the reason given, the contact it came from when one was attached, and when it was blocked. Read-only. This is the list to check first when somebody reports that a customer's email never arrived — a blocked sender produces no bounce and no notification, so there is nothing else to see.

Parameters

Field	Type	Required	Description
limit	integer	optional	How many entries to return, newest first. Up to 500. Default: 200

Example

curl -X POST https://app.chirply.io/api/v1/actions/spam.list_senders \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "limit": 200
  }'

Test with your API key

Over MCP the same operation is the tool spam_list_senders at https://app.chirply.io/api/mcp, same bearer token, same input.

Mark as spammer

spam.mark_contactwriteconfirm

Mark one contact as a spammer, or take the mark back. Marking blocks the contact, moves every message and call already logged against them into spam, and adds every email address and phone number on their record to this account's blocked-sender list — so anything they send afterwards is filed on arrival with no notification, no forwarding to the account's mailbox, no auto-reply and no AI agent reply. Nothing is deleted and nothing is sent: unmarking restores the contact, restores their communications to normal views, and takes their addresses off the blocklist. Getting this wrong makes a real customer's mail stop reaching the inbox without anybody being told, so confirm the person first.

Parameters

Field	Type	Required	Description
contact_id	string (uuid)	required	The contact to mark as a spammer, or to clear the mark from.
spam	boolean	optional	True marks them as a spammer and blocks their addresses; false clears the mark and unblocks them. Default: true
reason	string	optional	Why, in a few words — shown beside the entry on the Spam screen so the next person understands the decision. Optional, and never shown to the person being blocked.
block_future	boolean	optional	Whether to put their addresses on the blocked-sender list. True (the default) is what stops the next message. Set false to record the judgement and clear their existing threads while still letting their mail through — the right choice when the address is shared with somebody legitimate. Default: true

Example

curl -X POST https://app.chirply.io/api/v1/actions/spam.mark_contact \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
  }'

Test with your API key

Over MCP the same operation is the tool spam_mark_contact at https://app.chirply.io/api/mcp, same bearer token, same input.

Mark as spammers

spam.mark_contactswriteconfirm

Mark many contacts as spammers at once — the Spammer button in the contacts list's selection bar. Each contact gets exactly what `spam.mark_contact` does: blocked and hidden from the contacts list, every message and call already logged against them moved into spam, and every email address and phone number on their record added to this account's blocked-sender list, so anything they send afterwards is filed on arrival with no notification, no forwarding, no auto-reply and no AI agent reply. Runs as a background job (watch it with `bulk_jobs.get`); returns the job. Nothing is deleted and nothing is sent. Passing `spam: false` lifts the mark from every listed contact instead and lets their mail through again. Getting this wrong makes real customers' mail stop reaching the inbox with nobody told, so confirm the selection first.

Parameters

Field	Type	Required	Description
contact_ids	array of (string (uuid))	required	The contacts to mark (or clear). Ids outside this account are skipped.
spam	boolean	optional	True marks them as spammers and blocks their addresses; false clears the mark and unblocks them. Default: true
reason	string	optional	Why, in a few words — shown beside the entry on the Spam screen so the next person understands the decision. Optional, and never shown to the person being blocked.

Example

curl -X POST https://app.chirply.io/api/v1/actions/spam.mark_contacts \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_ids": [
      "2f6a1c1e-6c3b-4c62-9f6e-8a2d4b7c9e11"
    ]
  }'

Test with your API key

Over MCP the same operation is the tool spam_mark_contacts at https://app.chirply.io/api/mcp, same bearer token, same input.

Unblock a sender

spam.unblock_senderwrite

Take one email address, email domain or phone number off this account's blocked-sender list, so their next message reaches the inbox normally with notifications, forwarding and auto-replies. Messages already filed as spam stay in spam until they are restored individually. Sends nothing and costs nothing.

Parameters

Field	Type	Required	Description
kind	"email" \| "domain" \| "phone"	required	What is being blocked: `email` for one mailbox, `domain` for every mailbox at a domain and its subdomains (for a sender who keeps changing address), `phone` for one number however it is punctuated.
value	string	required	The address, domain or number to unblock, in any spelling — it is normalized the same way it was when blocked.

Example

curl -X POST https://app.chirply.io/api/v1/actions/spam.unblock_sender \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "email",
    "value": "example"
  }'

Test with your API key

Over MCP the same operation is the tool spam_unblock_sender at https://app.chirply.io/api/mcp, same bearer token, same input.

Save automatic spam detection

spam.update_auto_detectionwriteconfirmadmin only

Switch automatic spam detection on or off and choose what it does. When on, every inbound email from somebody the account has no relationship with is read by the account's OWN AI connection (OpenRouter — one short request per such email, billed to that account) before anything else happens to it. A confident spam verdict files the email as spam on arrival — no notification, no forwarding, no auto-reply, no AI agent reply — and, with `mark_senders`, also marks the sender as a spammer and blocks their address so later emails are filed without another AI call. Never judged: customers, anyone the account has emailed or texted, its own domains, and anyone a teammate has marked not spam. Every automatic mark says "Auto-detected" and is lifted from Settings → Spam & blocked senders. Saving sends nothing.

Parameters

Field	Type	Required	Description
enabled	boolean	required	True checks every inbound email from a stranger with AI and files spam on arrival; false stops checking.
mark_senders	boolean	optional	When an email is judged spam, also mark the sender as a spammer and block their address (true, the default), or only file that one email (false). Default: true
cold_pitches	boolean	optional	Count unsolicited sales pitches from strangers (SEO, web design, lead lists, outsourcing) as spam (true, the default), or only scams, phishing, malware and junk (false). Default: true

Example

curl -X POST https://app.chirply.io/api/v1/actions/spam.update_auto_detection \
  -H "Authorization: Bearer chp_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true
  }'

Test with your API key

Over MCP the same operation is the tool spam_update_auto_detection at https://app.chirply.io/api/mcp, same bearer token, same input.