Skip to main content
POST
/
inbound
/
email
/
webhook
curl -X POST https://api.avoca.ai/v1/inbound/email/webhook \
  -H "X-Webhook-Secret: YOUR_WEBHOOK_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "[email protected]",
    "to": ["[email protected]"],
    "subject": "AC not working - Need urgent help",
    "text": "Hi, my AC stopped working last night and it is very hot. Can someone come today? My address is 123 Main St.",
    "message_id": "<[email protected]>",
    "date": "2024-01-20T08:30:00Z",
    "spam_score": 0.1
  }'

{
  "data": {
    "processed": true,
    "customer_id": "cust_789",
    "conversation_id": "conv_email_456",
    "ticket_id": "12345",
    "auto_response_sent": true,
    "categorization": {
      "intent": "appointment_request",
      "urgency": "high",
      "sentiment": "negative",
      "service_type": "AC Repair"
    }
  },
  "meta": {
    "webhook_id": "wh_abc123",
    "timestamp": "2024-01-20T08:31:00Z"
  }
}
This webhook endpoint receives and processes incoming emails sent to your Avoca-powered email addresses. Emails are automatically parsed, categorized, and can trigger AI responses or create tickets.

​
Request

​
from
string
required
Sender’s email address
​
to
array
required
List of recipient email addresses
​
cc
array
List of CC recipients
​
subject
string
required
Email subject line
​
text
string
Plain text version of the email
​
html
string
HTML version of the email
​
message_id
string
required
Unique email message identifier
​
in_reply_to
string
Message ID this email is replying to
​
date
string
required
Email sent timestamp (ISO 8601)
​
attachments
array
List of email attachments
​
headers
object
Additional email headers
​
spam_score
number
Spam score (0-10, higher = more likely spam)

​
Response

​
processed
boolean
Whether the email was successfully processed
​
customer_id
string
Matched customer ID from ServiceTitan
​
conversation_id
string
Created or updated conversation ID
​
ticket_id
string
ServiceTitan ticket ID if created
​
auto_response_sent
boolean
Whether an automatic response was sent
​
categorization
object
AI categorization results
curl -X POST https://api.avoca.ai/v1/inbound/email/webhook \
  -H "X-Webhook-Secret: YOUR_WEBHOOK_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "[email protected]",
    "to": ["[email protected]"],
    "subject": "AC not working - Need urgent help",
    "text": "Hi, my AC stopped working last night and it is very hot. Can someone come today? My address is 123 Main St.",
    "message_id": "<[email protected]>",
    "date": "2024-01-20T08:30:00Z",
    "spam_score": 0.1
  }'

{
  "data": {
    "processed": true,
    "customer_id": "cust_789",
    "conversation_id": "conv_email_456",
    "ticket_id": "12345",
    "auto_response_sent": true,
    "categorization": {
      "intent": "appointment_request",
      "urgency": "high",
      "sentiment": "negative",
      "service_type": "AC Repair"
    }
  },
  "meta": {
    "webhook_id": "wh_abc123",
    "timestamp": "2024-01-20T08:31:00Z"
  }
}

​
Auto-Response Templates

Configure automatic responses based on email categorization: 
{
  "urgent_acknowledgment": {
    "subject": "Re: {original_subject} - We've Received Your Urgent Request",
    "body": "We understand this is urgent. Ticket #{ticket_number} has been created. A technician will call you within {estimated_response}."
  },
  "appointment_acknowledgment": {
    "subject": "Re: {original_subject} - Appointment Request Received",
    "body": "Thank you for your appointment request. We'll contact you within 2 hours to schedule your service."
  },
  "general_inquiry": {
    "subject": "Re: {original_subject} - Thank You for Contacting Us",
    "body": "We've received your message and will respond within 24 hours."
  }
}