AI-agent use case · powered by Ṣọ Shield API
Your AI agents open email. Protect them like employees.
This page shows agent builders where to place a security check before an agent reads email, follows a link, or acts on payment instructions. For endpoint reference and pricing, use the developer page.
POST /v1/email/analyze → { "verdict": "malicious", "overall_score": 78 }
Seven endpoints · Structured JSON verdicts · Zero retention · Free plan, no credit card
The threat model
Agents inherit every human threat. None of the suspicion.
A person reading a strange invoice hesitates. An agent does not. It cannot feel that something is off, so the check has to be explicit.
Agents act on untrusted input
Inbox triage, invoice processing, web research. Each of these workflows consumes content an attacker can write. The inbox is an open port into your agent's context.
Machine speed cuts both ways
An agent that processes hundreds of messages an hour can be phished at the same rate. One poisoned email can become an action loop before anyone is watching.
A fooled agent has real permissions
Send, pay, delete, forward. The blast radius of a deceived agent is exactly as large as the credentials you gave it.
Guardrail mapping
One call before every risky action
Each Ṣọ Shield endpoint maps to a moment where your agent is about to trust something. Call it first, branch on the verdict.
Acting on a message
Triage, summarize, reply, extract a task
POST /v1/email/analyze5 credits
A verdict of clean, caution, suspicious, or malicious, an overall risk score, category scores across BEC, phishing, spam, and malware, and the specific findings behind them.
Following a link
Web research, confirmation pages, tracking URLs
POST /v1/url/analyze1 credit
A risk verdict with a 0 to 100 risk score, flagging raw-IP hosts, suspicious TLDs, URL shorteners, and credential-in-URL tricks.
Trusting the sender identity
Before acting on what the CEO said
POST /v1/headers/validate1 credit
The email's own SPF, DKIM, and DMARC results read from its headers, plus From and Return-Path mismatch detection.
Trusting a counterparty
New vendor, new domain, new payment instructions
POST /v1/domain/check + /v1/bec/score1 + 2 credits
A domain reputation and typosquat check, plus a 0 to 100 BEC risk score from urgency, impersonation, and payment-request signals.
Paying an invoice
Accounts-payable and procurement agents
POST /v1/doc/compare3 credits
A comparison of two document versions that flags changed banking details, altered amounts, and new contact addresses.
Resolving a QR code
After your application extracts the QR destination
POST /v1/qr/scan2 credits
Checks the decoded destination using structural URL signals. Your application must decode the QR image before calling this endpoint.
Integration
The guardrail is one function
Analyze the message before the agent acts on it. If the verdict is malicious or the overall risk score is high, quarantine it and hand it to a person.
import requests
SHIELD = "https://api-service.soone.soemailsecurity.com"
def email_guardrail(message: dict) -> bool:
"""Call before the agent acts on any message. True means no threat was detected."""
resp = requests.post(
f"{SHIELD}/v1/email/analyze",
headers={"x-api-key": "so_live_..."}, # use so_test_... in development
json={
"from": message["from"],
"subject": message["subject"],
"body": message["body"],
},
timeout=15,
)
result = resp.json()["data"]
# Block on a malicious verdict, or a high overall risk score.
if result["verdict"] == "malicious" or result["overall_score"] >= 70:
quarantine(message)
alert_human(message, result) # a person reviews it, the agent does not act
return False
return True
for message in inbox.unread():
if email_guardrail(message):
agent.handle(message){
"data": {
"verdict": "malicious",
"overall_score": 78,
"category_scores": {
"bec": 30, "phishing": 60
},
"findings": [ ... ]
},
"meta": { "credits_charged": 5 }
}What the fields mean
verdictis the clean call: clean, caution, suspicious, or malicious.overall_scoreandcategory_scoreslet you tune how aggressive the guardrail is.findingslists the specific signals behind the verdict.
Zero retention
Your users' email passes through your agent. It never stays on our servers.
When your agent calls Ṣọ Shield, the submitted content is analyzed for the requested verdict and is not deliberately retained as an email or document archive.
For an agent builder, that means you can add a security layer while minimizing the amount of message content copied into another system. Review our privacy and API terms for the operational metadata the service still processes.
Analyzed in memory
Content is processed in memory and discarded when the response returns. Nothing is written to disk.
Less content to retain
Submitted message content is not kept as an inbox archive. Limited account, usage, security, and billing metadata is still processed to operate the service.
Google CASA verified
Our consumer application completed a Cloud Application Security Assessment. This is not a separate certification of every API endpoint.
Integration surface
Available today. Honest about tomorrow.
Available now
REST API, self-serve
Seven endpoints covering email, URLs, headers, domains, QR codes, and documents. Sign up in the dashboard, create a key, and call the API from any language. The free plan includes 3,000 credits a month, and so_test_ keys let you develop without spending them on live traffic.
Early access
MCP server for agent frameworks
An MCP server that exposes Ṣọ Shield verdicts as tools for Claude and GPT agent frameworks is in early access. It is not generally available yet, and we will not pretend it is. If you want it in your stack early, write to us.
Questions agent builders ask
What threats does Ṣọ Shield catch for AI agents?
Phishing and business email compromise in messages, risky URLs such as raw-IP hosts, suspicious TLDs and shortener tricks, likely brand-impersonation domains, QR codes that hide those same links, and altered payment details between invoice versions. Every check comes back as structured JSON your agent can branch on, so a bad verdict stops an action before it happens.
What is the latency, and can I run checks asynchronously?
Each check is a single HTTPS request, so the guardrail adds one round trip to the action it protects. Put synchronous checks in front of irreversible actions like sending, paying, or deleting. For bulk work such as inbox triage, run checks concurrently or queue them in your worker pool. Nothing about the API requires blocking your whole agent loop.
Do you store the content my agent submits?
No. Content is analyzed in memory and never stored on our servers. We do not keep copies of emails, URLs, headers, or documents after the response is returned. That is the zero-retention architecture, and it is why you can add Ṣọ Shield to an agent product without adding a data-retention liability.
How is this different from a spam filter?
A spam filter sits in front of a mailbox and drops bulk mail before delivery. Ṣọ Shield is an action-time verdict API. It answers a different question: should my agent trust this specific message, link, domain, or document right now? It returns a structured verdict with a risk score, and it covers surfaces spam filters never see, such as URLs found during web research, QR codes, and invoice documents.
How do agents authenticate?
With an API key sent in the x-api-key header. Keys are issued from the self-serve dashboard: so_live_ keys for production and so_test_ keys for development. The free plan includes 3,000 credits a month with no credit card required.
Give your agent a security team.
The free plan includes 3,000 credits a month. No credit card required.