Inbound Emails API

All endpoints require authentication and projects tool permissions.

Supports inbound emails for any resource type: project, deal, contact, company, candidate, or task.

List Inbound Emails

GET /api/inbound-emails

Permission: projects:view

Query parameters:

Param	Type	Required	Description
resource_type	string	Yes	Resource type (e.g. project, deal, contact)
resource_id	string	Yes	Resource ID
status	string	No	Filter by status

Response: { emails } — each email includes task_title if linked to a task. Limited to 100 results, ordered by received_at descending.

List Unrouted Emails

GET /api/inbound-emails/unrouted

Permission: projects:manage

Returns emails with resource_type = 'unrouted' for manual triage. Limited to 100 results.

Response: { emails }

Get Email

GET /api/inbound-emails/:id

Permission: projects:view

Response: { email } — includes task_title if linked.

Update Email

PUT /api/inbound-emails/:id

Permission: projects:update

Body:

Field	Type	Description
status	string	New status
task_id	string or null	Link/unlink a task
resource_type	string	Reassign resource type (requires resource_id)
resource_id	string	Reassign resource ID (requires resource_type)

When reassigning to a new resource, matched_by is set to manual.

Response: { email }

Delete Email

DELETE /api/inbound-emails/:id

Permission: projects:update

Response: { ok: true }

Convert to Task

POST /api/inbound-emails/:id/convert

Permission: projects:update

Creates a new task from the email’s subject and body. The task is linked to the email’s resource if it is a project or deal. The email status is set to converted and linked to the new task.

Response: { task }

Reply to Email

POST /api/inbound-emails/:id/reply

Permission: projects:update

Sends a threaded reply via the Gmail API. Includes the user’s email signature (if configured) and a quoted version of the original email. Threading is maintained via RFC822 Message-ID headers and Gmail thread IDs.

Body:

Field	Type	Required	Description
body	string	Yes	HTML body of the reply

The reply is stored as an outbound inbound_emails record with status read. The original email is also marked as read if previously unread.

Response: { ok: true, gmail_message_id, reply_id, thread_id }