Email Your Employees

Forward emails to your AI employees. They read the sender, subject, and body, then act on it using their full capabilities. Fire-and-forget: you get 202 Accepted immediately, the employee processes the email in the background.

TL;DR

POST an email to /api/email/ with your API key, an employee ID, and the email fields (body is required, sender and subject are optional). The employee picks it up and acts on it. No waiting for a response.

When to Use This

Use the email channel when you want emails to trigger employee work. Set up your email provider to forward incoming messages to the endpoint, and your employees handle them automatically.

• Support inbox. Forward customer support emails to a support employee
• Lead capture. Route inbound sales inquiries to a sales employee
• Internal requests. Forward expense reports, PTO requests, or approval emails
• Notifications. Route system alerts and notifications for automated triage
• RFP responses. Forward RFP emails to an employee who drafts responses

How It Works

The email endpoint accepts structured email fields and formats them into a rich prompt for the employee. The employee sees the sender, subject line, and body, giving it full context about what was sent and who sent it.

• Dedicated endpoint. POST /api/email/ with email-specific fields (from, subject, body)
• Fire-and-forget. You get 202 immediately, the employee processes in the background
• Rich context. The employee sees [Email from [email protected]] with subject and body, so it knows the message came via email
• Same execution. Identical pipeline to web chat, API, and webhooks
• Same billing. Credits are tracked and charged the same way
• Shared keys. API keys work across all programmatic channels

Enable the Channel

The Email channel is disabled by default. Enable it before sending emails:

1. Go to Settings > Technical > Channels
2. Find Email Webhook under the Programmatic group
3. Toggle it on

Authentication

Same as all programmatic channels. Bearer token in the Authorization header.

1. Go to Settings > Technical > Channels
2. Expand the Programmatic group
3. Expand any channel card
4. Click "New Key", give it a name, hit Enter
5. Copy the key from the green banner. It will not be shown again

Endpoint

POST /api/email/

Send an email to an AI employee.

Request body:

Request headers (optional):

Response (202 Accepted):

What the Employee Sees

The employee receives the email formatted with full context:

[Email from jane@example.com] Subject: Q3 Report Can you summarize last quarter sales numbers?

If from is omitted, the header shows [Email]. If subject is omitted, it is skipped. The employee knows the message came from email and can adjust its response accordingly.

Error Responses

Quick Start

curl

curl -X POST https://sistava.com/api/email/ \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "employee_id": "YOUR_EMPLOYEE_UUID",
    "from": "[email protected]",
    "subject": "Q3 Report",
    "body": "Can you summarize last quarter sales numbers?"
  }'

Python

import requests

requests.post(
    "https://sistava.com/api/email/",
    headers={"Authorization": "Bearer sk-your-api-key"},
    json={
        "employee_id": "YOUR_EMPLOYEE_UUID",
        "from": "[email protected]",
        "subject": "Q3 Report",
        "body": "Can you summarize last quarter sales numbers?",
    },
)
# 202: employee will handle it in the background

JavaScript / Node

await fetch("https://sistava.com/api/email/", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk-your-api-key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    employee_id: "YOUR_EMPLOYEE_UUID",
    from: "[email protected]",
    subject: "Q3 Report",
    body: "Can you summarize last quarter sales numbers?",
  }),
});
// 202: fire and forget

Connecting Your Email Provider

There are two ways to get mail into the endpoint. Use an inbound parse service (SendGrid, Mailgun, Postmark) when you want full control over the payload, or a plain email forwarding rule when you just want messages sent to an address to reach an employee. Either way, point it at https://sistava.com/api/email/ and make sure the request carries employee_id and body.

For a parse service, your middleware extracts the sender, subject, and body from the provider's format, then POSTs them to the endpoint.

Compatible with any provider that supports inbound email forwarding via HTTP:

Each provider has its own payload format. Build a small middleware that transforms the provider's format into the employee_id, from, subject, body fields this endpoint expects.

Outbound (Sending Emails)

Employees can send emails using the connected Gmail tool. Connect Gmail via OAuth in the employee's Tools tab, then the employee can compose and send emails as part of its workflow. This is separate from the inbound email channel described here.

Good to Know

• No response content. Email is fire-and-forget. If you need the employee's answer, use the REST API instead
• Team leaders. If the employee is a team leader, they may delegate the email to a team member
• Idempotency. Use the Idempotency-Key header to prevent duplicate processing during retries. The key is valid for 5 minutes
• Rate limit. 60 messages per 60 seconds per tenant. This limit is shared across all programmatic channels (API, MCP, webhook, email), not just email
• Body size. The body field cannot exceed 32 KB, and the total request payload cannot exceed 64 KB. For emails with large attachments, extract the text content and forward just that
• Managing keys. Create, rename, and revoke from the Channels page. Revoking blocks all channels immediately.

Troubleshooting

• 401 Unauthorized. Missing or invalid API key. Include Authorization: Bearer sk-... in the request header.
• 403 Forbidden. The email channel is not enabled. Enable it in Settings > Technical > Channels.
• 400 Bad Request. Check that employee_id is a valid UUID and body is a non-empty string. The body must be valid JSON.
• Employee not acting on the email. Make sure the body field contains clear, actionable text. Include from and subject for context so the employee understands who sent it and what it is about.

Frequently Asked Questions

Q: Are from and subject required? A: No. Only employee_id and body are required. However, including from and subject gives the employee much better context about the email, so they are strongly recommended.

Q: Can the employee reply to the email? A: Not directly through this channel. The employee processes the email as a task. If the employee has Gmail connected as a tool, it can compose and send a reply email as part of its workflow.

Q: How do I prevent duplicate emails from being processed? A: Include an Idempotency-Key header with a unique value per email (e.g., the email's Message-ID). Duplicates within 5 minutes are rejected.

Q: Can I forward emails with attachments? A: The endpoint accepts text only (no binary attachments). Extract the text content from attachments and include it in the body field, or upload files to the employee via the web app.

Q: Does the email channel support HTML emails? A: The body field is plain text. If you are forwarding HTML emails, strip the HTML tags and send the text content. The employee works with the text, not the formatting.