botserver/docs/src/chapter-10-api/email-api.md

Email API

The Email API provides endpoints for email operations including sending, receiving, and managing email accounts through the Stalwart mail server integration.

Overview

Email functionality in General Bots is available through:

1. REST API - Documented in this chapter
2. BASIC Keywords - SEND MAIL for scripts
3. Email Module - Background processing and IMAP/SMTP integration

Endpoints

Send Email

POST /api/email/send

Send an email message.

Request:

{
  "to": ["recipient@example.com"],
  "cc": ["cc@example.com"],
  "bcc": [],
  "subject": "Meeting Tomorrow",
  "body": "Hi, just a reminder about our meeting.",
  "body_type": "text",
  "attachments": []
}

Response:

{
  "message_id": "msg-abc123",
  "status": "sent",
  "timestamp": "2024-01-15T10:30:00Z"
}

Body Types:

• text - Plain text
• html - HTML formatted

List Emails

GET /api/email/inbox

Retrieve inbox messages.

Query Parameters:

• folder - Folder name (default: INBOX)
• limit - Number of messages (default: 50)
• offset - Pagination offset
• unread - Filter unread only (boolean)
• since - Messages since date (ISO 8601)

Response:

{
  "messages": [
    {
      "id": "email-001",
      "from": "sender@example.com",
      "subject": "Hello",
      "preview": "Just wanted to say hi...",
      "date": "2024-01-15T09:00:00Z",
      "read": false,
      "has_attachments": false
    }
  ],
  "total": 142,
  "unread_count": 5
}

Get Email

GET /api/email/:id

Get specific email details.

Response:

{
  "id": "email-001",
  "from": {
    "name": "John Doe",
    "email": "john@example.com"
  },
  "to": [
    {
      "name": "You",
      "email": "you@example.com"
    }
  ],
  "cc": [],
  "subject": "Meeting Notes",
  "body": "Here are the notes from today's meeting...",
  "body_html": "<p>Here are the notes from today's meeting...</p>",
  "date": "2024-01-15T09:00:00Z",
  "read": true,
  "attachments": [
    {
      "id": "att-001",
      "filename": "notes.pdf",
      "size": 102400,
      "content_type": "application/pdf"
    }
  ]
}

Delete Email

DELETE /api/email/:id

Delete an email message.

Response:

{
  "status": "deleted",
  "message_id": "email-001"
}

Get Attachment

GET /api/email/:id/attachments/:attachment_id

Download an email attachment.

Response: Binary file with appropriate Content-Type header.

Mark as Read

PUT /api/email/:id/read

Mark email as read.

Request:

{
  "read": true
}

Move Email

PUT /api/email/:id/move

Move email to a different folder.

Request:

{
  "folder": "Archive"
}

List Folders

GET /api/email/folders

List available email folders.

Response:

{
  "folders": [
    {
      "name": "INBOX",
      "path": "INBOX",
      "unread_count": 5,
      "total_count": 142
    },
    {
      "name": "Sent",
      "path": "Sent",
      "unread_count": 0,
      "total_count": 89
    },
    {
      "name": "Drafts",
      "path": "Drafts",
      "unread_count": 0,
      "total_count": 3
    }
  ]
}

Create Draft

POST /api/email/drafts

Create an email draft.

Request:

{
  "to": ["recipient@example.com"],
  "subject": "Draft subject",
  "body": "Draft content..."
}

Response:

{
  "draft_id": "draft-001",
  "status": "saved"
}

Send Draft

POST /api/email/drafts/:id/send

Send a previously saved draft.

Response:

{
  "message_id": "msg-abc123",
  "status": "sent"
}

Email Accounts

List Accounts

GET /api/email/accounts

List configured email accounts.

Response:

{
  "accounts": [
    {
      "id": "account-001",
      "email": "user@example.com",
      "provider": "stalwart",
      "status": "connected"
    }
  ]
}

Add Account

POST /api/email/accounts

Add a new email account.

Request:

{
  "email": "user@example.com",
  "imap_server": "imap.example.com",
  "imap_port": 993,
  "smtp_server": "smtp.example.com",
  "smtp_port": 587,
  "username": "user@example.com",
  "password": "app-specific-password"
}

Response:

{
  "account_id": "account-002",
  "status": "connected",
  "message": "Account added successfully"
}

BASIC Integration

Use email in your BASIC scripts:

' Simple email
SEND MAIL "recipient@example.com", "Subject", "Body"

' With variables
recipient = HEAR "Who should I email?"
subject = HEAR "What's the subject?"
body = HEAR "What's the message?"
SEND MAIL recipient, subject, body
TALK "Email sent!"

Configuration

Configure email in config.csv:

key,value
smtp-server,smtp.gmail.com
smtp-port,587
imap-server,imap.gmail.com
imap-port,993
email-username,your-email@gmail.com
email-password,your-app-password
email-from,Your Name <your-email@gmail.com>

Gmail Configuration:

• Use App Passwords (not your main password)
• Enable IMAP in Gmail settings
• Allow less secure apps or use OAuth

Stalwart Mail Server

When using the built-in Stalwart mail server:

Automatic Configuration:

• Server runs on standard ports (25, 993, 587)
• Accounts created through Zitadel integration
• TLS certificates auto-managed

Manual Configuration:

key,value
stalwart-enabled,true
stalwart-domain,mail.yourdomain.com
stalwart-admin-password,secure-password

Error Handling

Status Code	Error	Description
400	invalid_recipient	Invalid email address
401	unauthorized	Authentication required
403	forbidden	No access to mailbox
404	not_found	Email not found
422	send_failed	SMTP delivery failed
503	service_unavailable	Mail server offline

Rate Limits

Endpoint	Limit
Send	100/hour per user
Inbox	300/hour per user
Attachments	50/hour per user

Security Notes

1. Never hardcode credentials - Use config.csv
2. Use App Passwords - Not main account passwords
3. Enable TLS - Always use encrypted connections
4. Audit sending - Log all outbound emails

Database Schema

-- user_email_accounts
CREATE TABLE user_email_accounts (
    id UUID PRIMARY KEY,
    user_id UUID REFERENCES users(id),
    email TEXT NOT NULL,
    imap_server TEXT,
    smtp_server TEXT,
    encrypted_password TEXT,
    created_at TIMESTAMPTZ
);

-- email_drafts
CREATE TABLE email_drafts (
    id UUID PRIMARY KEY,
    user_id UUID REFERENCES users(id),
    recipients JSONB,
    subject TEXT,
    body TEXT,
    attachments JSONB,
    created_at TIMESTAMPTZ,
    updated_at TIMESTAMPTZ
);

See Also

• SEND MAIL Keyword - BASIC email
• CREATE DRAFT Keyword - Draft creation
• External Services - Service configuration