Skip to content
Nucleus

Emails API

All endpoints require authentication and emails tool permissions.

Sync

Section titled “Sync”

Trigger Sync

Section titled “Trigger Sync”
POST /api/emails/sync

Syncs the current user’s Gmail for emails involving known contacts. Returns { synced, errors }.

Sync Status

Section titled “Sync Status”
GET /api/emails/sync/status

Returns { sync: { sync_status, last_synced_at, last_history_id, error_message } }.

Threads

Section titled “Threads”

List Threads

Section titled “List Threads”
GET /api/emails/threads

Query params: search, company_id, contact_id, direction (inbound|outbound), page, per_page

Returns { threads, total, page, pages }. Each thread includes companies[] with matched company names.

Thread Detail

Section titled “Thread Detail”
GET /api/emails/threads/:threadId

Returns { messages } — all emails in the thread ordered chronologically.

Emails

Section titled “Emails”

List Emails

Section titled “List Emails”
GET /api/emails

Flat email list. Query params: search, page, per_page.

Single Email

Section titled “Single Email”
GET /api/emails/:id

Returns { email, contacts } with linked contact/company info.

Resource-Scoped

Section titled “Resource-Scoped”

By Company

Section titled “By Company”
GET /api/emails/by-company/:companyId

By Contact

Section titled “By Contact”
GET /api/emails/by-contact/:contactId

Send

Section titled “Send”

Send Email

Section titled “Send Email”
POST /api/emails/send

Body:

{
  "to": ["email@example.com"],
  "cc": ["optional@example.com"],
  "subject": "string",
  "body_html": "string",
  "contact_id": "optional",
  "company_id": "optional",
  "in_reply_to": "optional (RFC 822 Message-ID)",
  "thread_id": "optional (Gmail thread ID for reply)"
}

Sends via Gmail API and stores in the emails table. Returns { email_id, gmail_message_id, thread_id }.