Skip to main content

​
Email API

The Email API provides comprehensive Gmail integration with AI-powered composition, advanced search, drafts, labels, and bulk operations.

​
Authentication

Email endpoints require Gmail integration. Users must connect their Google account before using these endpoints.

​
Endpoints

​
List Messages

List inbox messages with pagination. 
GET /api/v1/gmail/messages
​
max_results
integer
default:"20"
Maximum number of messages to return
​
pageToken
string
Page token for pagination

​
Get Message

Get a specific message by ID. 
GET /api/v1/gmail/message/{message_id}

​
Search Messages

Advanced search with multiple filters. 
GET /api/v1/gmail/search
​
query
string
Free text search query
​
sender
string
Filter by sender email
​
recipient
string
Filter by recipient email
​
subject
string
Filter by subject
​
has_attachment
boolean
Filter messages with attachments
​
date_from
string
Filter messages after date (YYYY/MM/DD)
​
date_to
string
Filter messages before date (YYYY/MM/DD)
​
label
string
Filter by label
​
is_read
boolean
Filter by read/unread status

​
Send Email

Send an email with optional attachments. 
POST /api/v1/gmail/send
Form data:
  • to (required) - Recipient email(s), comma-separated
  • subject (required) - Email subject
  • body (required) - Email body
  • cc (optional) - CC recipients, comma-separated
  • bcc (optional) - BCC recipients, comma-separated
  • is_html (optional) - Whether body is HTML
  • thread_id (optional) - Thread ID to reply to
  • attachments (optional) - File uploads

​
Send Email (JSON)

Send email without attachments using JSON. 
POST /api/v1/gmail/send-json
Request
{
  "to": ["[email protected]"],
  "subject": "Project Update",
  "body": "Here's the latest update...",
  "cc": ["[email protected]"],
  "bcc": []
}

​
AI Composition

​
Compose with AI

Generate email content with AI assistance. 
POST /api/v1/mail/ai/compose
Request
{
  "prompt": "Write a professional email declining a meeting",
  "subject": "Re: Meeting Request",
  "body": "",
  "writingStyle": "Professional",
  "contentLength": "Medium",
  "clarityOption": "Clear and concise"
}
Response
{
  "subject": "Re: Meeting Request - Unable to Attend",
  "body": "Dear [Name],\n\nThank you for your meeting invitation..."
}

​
Message Actions

​
Mark as Read

Mark messages as read. 
POST /api/v1/gmail/mark-as-read
Request
{
  "message_ids": ["msg_1", "msg_2", "msg_3"]
}

​
Mark as Unread

Mark messages as unread. 
POST /api/v1/gmail/mark-as-unread

​
Star Messages

Add star to messages. 
POST /api/v1/gmail/star

​
Unstar Messages

Remove star from messages. 
POST /api/v1/gmail/unstar

​
Trash Messages

Move messages to trash. 
POST /api/v1/gmail/trash

​
Restore Messages

Restore messages from trash. 
POST /api/v1/gmail/untrash

​
Archive Messages

Archive messages (remove from inbox). 
POST /api/v1/gmail/archive

​
Move to Inbox

Move messages to inbox. 
POST /api/v1/gmail/move-to-inbox

​
Drafts

​
List Drafts

Get all draft emails. 
GET /api/v1/gmail/drafts

​
Create Draft

Create a new draft. 
POST /api/v1/gmail/drafts
Request
{
  "to": ["[email protected]"],
  "subject": "Draft Email",
  "body": "Email content...",
  "is_html": false
}

​
Get Draft

Get a specific draft. 
GET /api/v1/gmail/drafts/{draft_id}

​
Update Draft

Update an existing draft. 
PUT /api/v1/gmail/drafts/{draft_id}

​
Delete Draft

Delete a draft. 
DELETE /api/v1/gmail/drafts/{draft_id}

​
Send Draft

Send an existing draft. 
POST /api/v1/gmail/drafts/{draft_id}/send

​
Labels

​
List Labels

Get all Gmail labels. 
GET /api/v1/gmail/labels

​
Create Label

Create a new label. 
POST /api/v1/gmail/labels
Request
{
  "name": "Important Projects",
  "label_list_visibility": "labelShow",
  "message_list_visibility": "show"
}

​
Update Label

Update an existing label. 
PUT /api/v1/gmail/labels/{label_id}

​
Delete Label

Delete a label. 
DELETE /api/v1/gmail/labels/{label_id}

​
Apply Labels

Apply labels to messages. 
POST /api/v1/gmail/messages/apply-label
Request
{
  "message_ids": ["msg_1", "msg_2"],
  "label_ids": ["label_1", "label_2"]
}

​
Remove Labels

Remove labels from messages. 
POST /api/v1/gmail/messages/remove-label

​
Email Threads

​
Get Thread

Get a complete email thread. 
GET /api/v1/gmail/thread/{thread_id}
Response
{
  "thread_id": "thread_123",
  "messages_count": 5,
  "thread": {
    "id": "thread_123",
    "messages": [...]
  }
}

​
Email Importance

​
Get Importance Summaries

Get AI-generated importance summaries for emails. 
GET /api/v1/gmail/importance-summaries
​
limit
integer
default:"50"
Maximum number of summaries
​
important_only
boolean
default:"false"
Only return important emails

​
Get Single Importance Summary

Get importance summary for a specific email. 
GET /api/v1/gmail/importance-summary/{message_id}

​
Bulk Importance Summaries

Get summaries for multiple emails. 
POST /api/v1/gmail/importance-summaries/bulk
Request
{
  "message_ids": ["msg_1", "msg_2", "msg_3"]
}

​
Next Steps

Workflows API

Automate email workflows

Calendar API

Manage calendar events

Build docs developers (and LLMs) love

Get started for freeTalk to us