POST Email Analyze API
/api/v1/ai/email-analyze
Analyze incoming emails using AI to extract structured insights such as category, intent, priority, sentiment, language, entities, and summary.
Architecture Role & AI Definition
Email Analyze API provides low-latency, deterministic REST execution for production engineering workflows. It processes structured payloads with strict schema validation, returns uniform JSON envelopes, and is secured via SHA-256 API key authentication with atomic credit pre-authorization locks.
Production Reliability Guidelines
Configure a hard client timeout of 5 to 8 seconds. If network latency spikes, cancel connection to avoid holding open sockets in worker pools.
Upon receiving 429 Rate Limit or transient 5xx, pause with exponential backoff:
wait = min(max_backoff, base * 2^attempt + jitter).
RSFlowHub acquires an atomic lock verifying base credits before model invocation. If validation fails, zero credits are deducted.
Request Body Parameters
| Field | Type | Required | Description |
|---|---|---|---|
email_content |
string | Required | The main body of the email to analyze (Max: 20,000 characters). |
subject |
string | Optional | Optional email subject line. Providing this increases analysis accuracy. |
allowed_categories |
array of strings | Optional | Optional list of allowed categories. If provided, the AI forces the output category into one of these buckets. |
allowed_intents |
array of strings | Optional | Optional list of allowed intents. If provided, the AI forces the output intent into one of these buckets. |
custom_instructions |
string | Optional | Optional specific guidelines to customize the analysis or extraction process. |
Recommended API Pipeline
RSFlowHub email automation APIs are designed to work together sequentially. In a typical flow, you first Analyze the email, then generate a tailored Reply based on the analysis, and finally determine the Workflow routing decision.
Example Request
Send an email body with optional lists of expected categories and intents to get structured analysis data.
{
"subject": "Double charged on my last invoice!",
"email_content": "Hello, I was looking at my bank statement and I was charged twice for my Pro subscription this month. Please refund one of the charges immediately as this is unacceptable.",
"allowed_categories": ["support", "billing", "spam", "sales"],
"allowed_intents": ["refund_request", "cancellation", "login_issue"]
}curl -X POST https://rsflowhub.com/api/v1/ai/email-analyze \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"subject": "Double charged on my last invoice!",
"email_content": "Hello, I was looking at my bank statement and I was charged twice for my Pro subscription this month. Please refund one of the charges immediately as this is unacceptable.",
"allowed_categories": ["support", "billing", "spam", "sales"],
"allowed_intents": ["refund_request", "cancellation", "login_issue"]
}'Example Response
The API analyzes the text using AI and returns high-accuracy structured insights.
{
"success": true,
"request_id": "req_7f3a9c2d1e4b8a6f",
"data": {
"result": {
"category": "billing",
"intent": "refund_request",
"priority": "high",
"sentiment": "negative",
"language": "en",
"entities": {
"charge_amount": "$49",
"billing_cycle": "monthly"
},
"summary": "The customer was double charged for their Pro subscription and is demanding an immediate refund."
}
},
"meta": {
"version": "v1",
"timestamp": "2026-09-27T12:34:56+00:00"
}
}API Request Example
Use the cURL snippet below to test the endpoint.
curl -X POST 'https://rsflowhub.com/api/v1/ai/email-analyze' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"subject": "Issue with login",
"email_content": "I cannot sign in to my account. It says password incorrect.",
"allowed_categories": [
"support",
"billing",
"sales"
]
}'Want to try it without code? Test this request in the live Playground.
Common Failure Modes & Troubleshooting Matrix
| HTTP Code | Error Code | Root Cause | Recommended Remediation |
|---|---|---|---|
| 401 | API_KEY_MISSING / INVALID_API_KEY |
No key sent, or the key was mistyped or regenerated. | Copy the current key from Dashboard → API Keys and send it as Authorization: Bearer (or X-API-Key). |
| 402 | INSUFFICIENT_CREDITS |
Your balance cannot cover the estimate for this call (base 2 credits plus input/output size). | Buy a plan in Dashboard → Billing. Nothing was charged. |
| 422 | VALIDATION_ERROR |
A field is missing, too long or the wrong type, or the body is not valid JSON. | Read error.details for the field messages and fix the request. Do not retry the same body. |
| 429 | RATE_LIMIT_EXCEEDED |
Your plan-wide or per-endpoint per-minute limit was reached. | Wait the seconds in the Retry-After header, then retry with jitter. Rate limits |
| 502 | AI_PROVIDER_ERROR |
The AI model and its backup both failed. | Retry with backoff and check the status page. Nothing was charged. |