import { createClient } from "@mailsai/sdk";
const client = createClient(); // reads MAILS_API_KEY
const result = await client.messages.appeal({
agent: "hello",
subject: "Checking in on order #10473",
body_text: "Your order #10473 was delivered.",
});
console.log(result);from mailsai import create_client
client = create_client() # reads MAILS_API_KEY
result = client.appeal(
agent="hello",
subject="Checking in on order #10473",
body_text="Your order #10473 was delivered.",
)
print(result)curl -X POST 'https://api.mails.ai/v1/messages/appeal' \
-H "Authorization: Bearer $MAILS_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"agent": "hello",
"subject": "Checking in on order #10473",
"body_text": "Your order #10473 was delivered."
}'mails emails appeal --subject "Your invoice" \
--body-text "Hi Jordan, your invoice is attached."{
"name": "mails_emails_appeal",
"arguments": {
"agent": "hello",
"subject": "Checking in on order #10473",
"body_text": "Your order #10473 was delivered."
}
}{
"outcome": "overturned",
"message": "<message>",
"review_score": 0,
"reason": "<reason>",
"replayed": false
}200 The review outcome.
400 Invalid request — malformed JSON or a field failed
validation. Also feature_not_enabled when this
server has a feature switched off (custom domains
before they are available).
401 Missing or invalid API key.
403 The API key lacks the required scope
(insufficient_scope), or the token belongs to an
app connected by sign-in and this operation is
closed to connected apps
(connected_app_not_allowed).
404 Resource not found in this workspace, or the agent
a send names is archived (agent_archived).
429 Rate or quota limit exceeded. The body's resets_at
and retry_after_seconds say when the request can
succeed. A Retry-After header is sent only when
that is 60 seconds or less; a longer wait (an
hourly, daily or monthly cap) sends none, so retry
at resets_at or raise the limit instead of
sleeping.
500 Internal server error.Appeal a cold-firewall refusal
cold_email_prohibited.import { createClient } from "@mailsai/sdk";
const client = createClient(); // reads MAILS_API_KEY
const result = await client.messages.appeal({
agent: "hello",
subject: "Checking in on order #10473",
body_text: "Your order #10473 was delivered.",
});
console.log(result);from mailsai import create_client
client = create_client() # reads MAILS_API_KEY
result = client.appeal(
agent="hello",
subject="Checking in on order #10473",
body_text="Your order #10473 was delivered.",
)
print(result)curl -X POST 'https://api.mails.ai/v1/messages/appeal' \
-H "Authorization: Bearer $MAILS_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"agent": "hello",
"subject": "Checking in on order #10473",
"body_text": "Your order #10473 was delivered."
}'mails emails appeal --subject "Your invoice" \
--body-text "Hi Jordan, your invoice is attached."{
"name": "mails_emails_appeal",
"arguments": {
"agent": "hello",
"subject": "Checking in on order #10473",
"body_text": "Your order #10473 was delivered."
}
}{
"outcome": "overturned",
"message": "<message>",
"review_score": 0,
"reason": "<reason>",
"replayed": false
}200 The review outcome.
400 Invalid request — malformed JSON or a field failed
validation. Also feature_not_enabled when this
server has a feature switched off (custom domains
before they are available).
401 Missing or invalid API key.
403 The API key lacks the required scope
(insufficient_scope), or the token belongs to an
app connected by sign-in and this operation is
closed to connected apps
(connected_app_not_allowed).
404 Resource not found in this workspace, or the agent
a send names is archived (agent_archived).
429 Rate or quota limit exceeded. The body's resets_at
and retry_after_seconds say when the request can
succeed. A Retry-After header is sent only when
that is 60 seconds or less; a longer wait (an
hourly, daily or monthly cap) sends none, so retry
at resets_at or raise the limit instead of
sleeping.
500 Internal server error.Body Parameters
Agent name or id the refused send used. Optional — omitted, the workspace's single agent is assumed (the refused send itself created one if none existed).
The refused message's subject, verbatim.
The refused message's body_text, verbatim.
The refused message's body_html, verbatim.
Submit the SAME subject and body the refused send used. An independent reviewer re-judges it under the identical policy: overturned clears exactly that content for 24 hours (the identical send then goes through); upheld means the refusal stands; not_appealable means the block is deterministic policy (prohibited content, bulk list language, multi-signal cold pitches) and no review exists; not_blocked means the content is not refused at all. Identical content replays its stored outcome — an appeal is never a re-roll. Limit: 10 appeals per workspace per 24 hours.
Response
Result of the review: overturned (the same subject and body go through for the next 24 hours), upheld (the refusal stands), not_appealable (a policy block no review can lift) or not_blocked (the content is not refused; send it as it is).
Human-readable explanation of the outcome and what to do next.
The second reviewer's cold score (0 = clearly transactional, 1 = clearly cold). Absent for not_appealable/not_blocked.
The reviewer's one-line reason, when a review ran.
True when this outcome was served from a prior appeal of identical content.
Was this page helpful?