API Documentation

AI Email API — Pro feature

The ByteSMTP API lets you programmatically send email, read your inbox, and access AI-powered email features. All endpoints return JSON.

API access requires a Pro subscription.

Upgrade to Pro to get your API key →

Authentication

All API requests must include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

You can find your API key in the dashboard under Settings → API Key.

Endpoints

POST /api/send

Send an email message.

Request Body

{
  "from": "[email protected]",
  "to": "[email protected]",
  "subject": "Hello from ByteSMTP",
  "body": "This is the email body in plain text or HTML.",
  "cc": "[email protected]"
}

Parameters

Field	Type	Required	Description
`from`	string	Yes	Sender address (must be a mailbox you own)
`to`	string	Yes	Recipient email address
`subject`	string	Yes	Email subject line
`body`	string	Yes	Email body (plain text or HTML)
`cc`	string	No	CC recipient(s), comma-separated

Response

{
  "ok": true,
  "message": "Email sent successfully"
}

GET /api/inbox

List messages in a mailbox folder.

Query Parameters

Param	Type	Default	Description
`folder`	string	INBOX	Mail folder (INBOX, Sent, Drafts, Trash, Junk)
`page`	integer	1	Page number for pagination

Response

{
  "ok": true,
  "messages": [
    {
      "uid": 142,
      "from": "[email protected]",
      "subject": "Meeting tomorrow",
      "date": "2026-04-01T10:30:00Z",
      "seen": false
    }
  ],
  "page": 1,
  "total": 47
}

GET /api/message/{uid}

Read a specific message by UID.

Response

{
  "ok": true,
  "message": {
    "uid": 142,
    "from": "[email protected]",
    "to": "[email protected]",
    "subject": "Meeting tomorrow",
    "date": "2026-04-01T10:30:00Z",
    "body_text": "Let's meet at 2pm.",
    "body_html": "<p>Let's meet at 2pm.</p>",
    "attachments": []
  }
}

DELETE /api/message/{uid}

Delete a message by UID. Moves to Trash (or permanently deletes if already in Trash).

Response

{
  "ok": true,
  "message": "Message deleted"
}

POST /api/ai/generate

Use AI-powered email features: compose, reply, summarize, or improve emails.

Request Body

{
  "feature": "compose",
  "prompt": "Write a professional follow-up email about our Q2 budget proposal",
  "domain_id": 1,
  "provider": "openai"
}

Parameters

Field	Type	Required	Description
`feature`	string	Yes	AI feature: `compose`, `reply`, `summarize`, `improve`
`prompt`	string	Yes	Instructions or email content to process
`domain_id`	integer	No	Domain ID for context (used in compose/reply)
`provider`	string	No	AI provider: `openai` (default) or `anthropic`

Response

{
  "ok": true,
  "result": "Dear Team,\n\nI wanted to follow up on our Q2 budget proposal..."
}

Rate Limits

Endpoint	Limit
POST /api/send	100 requests/hour
GET /api/inbox	300 requests/hour
GET /api/message/{uid}	300 requests/hour
DELETE /api/message/{uid}	100 requests/hour
POST /api/ai/generate	50 requests/hour

Exceeding rate limits returns 429 Too Many Requests. The response includes a Retry-After header.

Error Responses

All errors follow the same format:

{
  "ok": false,
  "error": "Description of what went wrong"
}

Status	Meaning
400	Bad request (missing or invalid parameters)
401	Unauthorized (missing or invalid API key)
403	Forbidden (Pro subscription required)
404	Not found (message or resource doesn't exist)
429	Rate limit exceeded
500	Internal server error

Get Started

API access requires a Pro subscription ($4.99/month per mailbox).

Upgrade to Pro to get your API key →