POST Email Workflow API
/api/v1/ai/email-workflow
Determine the most appropriate business action for an email using AI. The API analyzes the email and recommends workflow decisions such as replying, forwarding, assigning, archiving, escalating, or routing.
Architecture Role & AI Definition
Email Workflow 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 route (Max: 20,000 characters). |
subject |
string | Optional | Optional email subject line. |
allowed_actions |
array of strings | Optional | Optional strict list of allowed actions (e.g., ["reply", "forward", "archive", "escalate"]). |
allowed_departments |
array of strings | Optional | Optional strict list of allowed departments (e.g., ["support", "billing", "sales", "hr"]). |
workflow_first |
boolean | Optional | Optional. If true, runs in Workflow-First Mode. The API internally executes both analysis and reply drafting, returning all results (insights and drafted reply) in a single unified JSON response. Default is false. |
custom_instructions |
string | Optional | Optional instructions to guide routing decisions. |
model |
string | Optional | Optional AI model to use. |
Enterprise Flexibility: Workflow-First Approach
For enterprise environments looking to minimize latency and API call overhead, you can enable workflow_first: true. Instead of making three separate calls (Analyze → Reply → Workflow), the Email Workflow API performs all of these actions internally and delivers a unified routing, analysis, and draft response in a single API round-trip.
Example Request (Workflow-First)
Requesting action and department routing while enabling workflow_first to get a single unified payload.
{
"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.",
"allowed_actions": ["reply", "forward", "escalate", "archive"],
"allowed_departments": ["support", "billing", "sales"],
"workflow_first": true
}curl -X POST https://rsflowhub.com/api/v1/ai/email-workflow \
-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.",
"allowed_actions": ["reply", "forward", "escalate", "archive"],
"allowed_departments": ["support", "billing", "sales"],
"workflow_first": true
}'Example Response
Because workflow_first: true was passed, the API outputs the routing decision along with nested analysis and reply drafts.
{
"success": true,
"data": {
"result": {
"action": "reply",
"department": "billing",
"confidence": 0.98,
"reasoning": "The customer is reporting a billing issue requiring an immediate refund, matching the billing department scope.",
"analysis": {
"category": "billing",
"intent": "refund_request",
"priority": "high",
"sentiment": "negative",
"language": "en",
"entities": {
"refund_amount": "$49"
},
"summary": "Customer demands refund for double charge on subscription."
},
"reply": {
"reply_text": "Hi John, Thank you for reaching out. We have received your query regarding the duplicate $49 charge on your invoice and have routed this to our billing specialist for priority review.",
"requires_human_escalation": false,
"escalation_reason": null
}
}
},
"meta": {
"credits_used": 3,
"credits_remaining": 995
}
}API Request Example
Use the cURL snippet below to test the endpoint.
curl -X POST 'https://rsflowhub.com/api/v1/ai/email-workflow' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"subject": "Cancel order #8849",
"email_content": "Please cancel order 8849.",
"allowed_actions": [
"reply",
"forward",
"escalate"
],
"workflow_first": false
}'Common Failure Modes & Troubleshooting Matrix
| HTTP Code | Error Code | Root Cause | Recommended Remediation |
|---|---|---|---|
| 400 | bad_request |
Malformed JSON syntax or missing required top-level parameters. | Validate JSON payload with Content-Type: application/json and ensure all required fields are present. |
| 401 | unauthorized |
Missing, revoked, or incorrectly formatted x-api-key header. |
Verify API key exists in Dashboard → API Keys and pass in x-api-key or Authorization: Bearer. |
| 402 | insufficient_credits |
Account credit balance is lower than the base required credits (2 credits). | Top up credits in billing settings or enable auto-recharge to prevent pipeline interruption. |
| 422 | validation_error |
Input failed parameter constraints (e.g., character length exceeded or invalid array types). | Review parameters table above and adjust payload length, types, or structure accordingly. |
| 429 | rate_limit_exceeded |
Concurrency limit (60 requests/minute default) reached for this endpoint key. | Back off and retry using the timestamp in Retry-After response header, or batch requests. |