POST Email Reply API
/api/v1/ai/email-reply
Generate intelligent, context-aware email replies based on the original email and optional analysis results. Customize the response with different tones, writing styles, languages, and business instructions to produce professional, human-like replies.
Architecture Role & AI Definition
Email Reply 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_text |
string | Required | The raw text of the incoming email (Max: 20,000 characters). |
context |
string | Optional | Optional general context or instructions for drafting the reply. |
tone |
string | Optional | Tone of the reply (e.g., "professional", "empathetic", "casual"). |
sender_name |
string | Optional | Name of the person who sent the email. |
recipient_name |
string | Optional | Name of your team or agent. |
knowledge_base |
array of strings | Optional | Array of factual sentences the AI must use to answer questions (e.g., ["Business hours are 9-5", "No refunds after 30 days"]). |
rules |
array of strings | Optional | Strict rules for the AI to follow (e.g., ["Never promise a refund", "Always escalate chargebacks"]). |
model |
string | Optional | Optional AI model to use. |
Credit Cost Optimization
This endpoint uses per_character billing. Do not send your entire company handbook in the knowledge_base on every API request.
For maximum efficiency, query your own database first to find the 2-3 relevant sentences, and pass only those sentences to the API.
Example Request (Autopilot Mode)
Pass specific rules and a knowledge base to strictly constrain the AI's behavior, ensuring it never hallucinates dangerous promises to customers.
{
"email_text": "Hi, I was charged $49 but I cancelled my account yesterday. Please refund me immediately or I will dispute the charge.",
"sender_name": "John Doe",
"recipient_name": "Support Team",
"knowledge_base": [
"Refunds are only issued if requested within 14 days of the charge.",
"Standard response time is 24 hours."
],
"rules": [
"Never promise a refund if you are unsure.",
"Be empathetic but firm.",
"If the user threatens a chargeback, escalate to a human."
],
"tone": "professional"
}curl -X POST https://rsflowhub.com/api/v1/ai/email-reply \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"email_text": "Hi, I was charged $49 but I cancelled my account yesterday. Please refund me immediately or I will dispute the charge.",
"knowledge_base": ["Refunds are only issued if requested within 14 days of the charge."],
"rules": ["If the user threatens a chargeback, escalate to a human."],
"tone": "professional"
}'Example Response
The API safely structures the response. In this example, because the customer threatened a chargeback, the AI followed the rule and flagged requires_human_escalation: true so your automation platform knows to pause the email.
{
"success": true,
"data": {
"result": {
"reply_text": "Hi John, Thank you for reaching out to the Support Team. I understand you are frustrated about the recent $49 charge after cancelling your account. I have escalated this ticket to a billing specialist who will review your account and get back to you within 24 hours.",
"confidence_score": 0.85,
"requires_human_escalation": true,
"escalation_reason": "Customer threatened a chargeback dispute.",
"triggered_actions": ["escalate_to_billing_specialist"]
}
},
"meta": {
"credits_used": 2,
"credits_remaining": 988
}
}API Request Example
Use the cURL snippet below to test the endpoint.
curl -X POST 'https://rsflowhub.com/api/v1/ai/email-reply' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"email_text": "Hi, I need help logging in.",
"knowledge_base": [
"Password resets can be done at /reset"
],
"rules": [
"Keep it short"
]
}'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. |