AIThreads Documentation

AIThreads provides email infrastructure for AI agents. Create managed inboxes, receive emails via webhooks, and send replies through our API.

Quickstart

Get started in 5 minutes:

1. Create an account

Sign up at aithreads.io/sign-up and create an organization.

2. Generate an API key

Go to your dashboard → Settings → API Keys → Create New Key

3. Create your first inbox

curl -X POST https://api.aithreads.io/v1/agent/inboxes \
  -H "Authorization: Bearer ait_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "support",
    "name": "Support Team"
  }'

4. Set up your webhook

Configure a webhook URL in your inbox settings to receive incoming emails.

5. Send a reply

curl -X POST https://api.aithreads.io/v1/agent/inboxes/{inbox_id}/messages \
  -H "Authorization: Bearer ait_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": [{"email": "customer@example.com"}],
    "subject": "Re: Your inquiry",
    "text_body": "Thank you for reaching out..."
  }'

Core Concepts

Organizations

Organizations are the top-level container for all resources. Each organization has its own inboxes, domains, and settings.

Inboxes

Inboxes are email addresses that can send and receive emails. Each inbox gets an address like support@yourorg.aithreads.io.

Threads

Emails are automatically grouped into threads based on subject and message headers. Threads maintain conversation history.

Labels

Labels help organize threads within an inbox. Create custom labels like "urgent", "resolved", or "needs-follow-up".

Knowledge Base

Upload documents to give your AI agent context. We generate embeddings for semantic search.

API Keys

API keys are the recommended way to authenticate for agent/programmatic access.

Authorization: Bearer ait_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Key Format

API keys start with ait_ followed by a UUID. Keys are scoped to a single organization.

Permissions

JWT Tokens

JWT tokens are used for dashboard/user authentication. Obtain a token by logging in:

curl -X POST https://api.aithreads.io/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "your_password"
  }'

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "usr_abc123",
    "email": "you@example.com",
    "name": "Your Name"
  }
}

Create Inbox

Create a new email inbox for your organization.

Request Body

Example

curl -X POST https://api.aithreads.io/v1/agent/inboxes \
  -H "Authorization: Bearer ait_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "support",
    "name": "Support Team"
  }'

{
  "id": "inb_abc123",
  "address": "support@acme.aithreads.io",
  "local_part": "support",
  "domain": "acme.aithreads.io",
  "display_name": "Support Team",
  "is_active": true,
  "created_at": "2024-01-15T10:30:00Z"
}

List Inboxes

Retrieve all inboxes for your organization.

Response

{
  "data": [
    {
      "id": "inb_abc123",
      "address": "support@acme.aithreads.io",
      "display_name": "Support Team",
      "thread_count": 142,
      "unread_thread_count": 5,
      "is_active": true
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 20,
    "offset": 0
  }
}

Update Inbox

Update inbox settings including display name, webhook URL, and agent prompt.

Request Body

Delete Inbox

Permanently delete an inbox and all associated data.

Send Email

Send an email from your inbox.

Request Body

* At least one of text_body or html_body is required.

Example

curl -X POST https://api.aithreads.io/v1/agent/inboxes/inb_abc123/messages \
  -H "Authorization: Bearer ait_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": [{"email": "customer@example.com", "name": "John Doe"}],
    "subject": "Re: Your inquiry",
    "text_body": "Thank you for reaching out. Here is the information you requested...",
    "thread_id": "thr_xyz789"
  }'

Receive Webhooks

When an email is received, we'll POST to your configured webhook URL.

Webhook Payload

{
  "event": "email.received",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "email_id": "eml_abc123",
    "thread_id": "thr_xyz789",
    "inbox_id": "inb_def456",
    "from": {
      "email": "customer@example.com",
      "name": "John Doe"
    },
    "to": [{"email": "support@acme.aithreads.io"}],
    "subject": "Need help with my order",
    "text_body": "Hi, I placed an order yesterday...",
    "received_at": "2024-01-15T10:30:00Z"
  }
}

Verifying Webhooks

We sign all webhook requests with HMAC-SHA256. Verify using your webhook secret:

X-AIThreads-Signature: sha256=abc123...

List Messages

Get all messages in a thread.

List Threads

Get all threads in an inbox.

Query Parameters

Get Thread

Get thread details with all messages.

Thread Labels

Labels help organize threads. Create labels per inbox, then apply them to threads.

Create Label

{
  "name": "urgent",
  "color": "#EF4444",
  "description": "Needs immediate attention"
}

Upload Document

Upload a document to the knowledge base. Supported formats: PDF, TXT, MD, DOC, DOCX.

Request

Use multipart/form-data:

curl -X POST https://api.aithreads.io/v1/agent/inboxes/inb_abc123/documents \
  -H "Authorization: Bearer ait_your_api_key" \
  -F "file=@product-manual.pdf" \
  -F "name=Product Manual"

Documents are automatically processed for semantic search using AI embeddings.

Search Documents

Semantic search across your knowledge base.

Get Context for RAG

Use the context endpoint to get relevant document snippets for your AI agent:

{
  "query": "refund policy",
  "context": "--- Document: Returns Policy (relevance: 0.89) ---\nCustomers may request a refund within 30 days...",
  "count": 3
}

Delete Document

Remove a document from the knowledge base.

Add Domain

Add a custom domain to send emails from your own domain.

{
  "domain": "mail.example.com"
}

After adding, you'll receive DNS records to configure.

Verify Domain

Check if DNS records are properly configured.

DNS Records

Required DNS records for custom domains:

Webhook Events

Events that trigger webhook notifications:

Webhook Security

All webhooks are signed using HMAC-SHA256 with your webhook secret.

Verification Example (Node.js)

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Retry Policy

Failed webhook deliveries are retried with exponential backoff:

• Attempt 1: Immediate
• Attempt 2: After 1 minute
• Attempt 3: After 5 minutes
• Attempt 4: After 30 minutes
• Attempt 5: After 2 hours

A delivery is considered successful if your endpoint returns a 2xx status code within 30 seconds.