# Email

Send and receive emails via TrustPager Mail or Gmail, manage threads, view logs, and configure email settings. Supports provider selection for Gmail integration.

**Base URL:** `https://api.trustpager.com/functions/v1/api/v1`

## Endpoints

### GET /email/threads

List email threads with linked entities (contacts, deals, customers). Supports full-text subject search, entity-based filtering, participant email filtering, and direction filtering.

**Scopes:** `email:read` — [full detail](./email/get-email-threads.md)

### GET /email/threads/:id

Retrieve a single email thread with linked entities.

**Scopes:** `email:read` — [full detail](./email/get-email-threads-id.md)

### GET /email/threads/:id/messages

List all messages (inbound and outbound) in a thread, sorted chronologically. Inbound messages include an "attachments" array with attachment metadata (name, mimeType, size). Outbound messages include "has_attachment" (boolean) and "attachment_filename" (string or null).

**Scopes:** `email:read` — [full detail](./email/get-email-threads-id-messages.md)

### POST /email/send

Send a new email. Default mode is "company" (uses configured Company Mail provider). Use mode "personal" with sender_user_id to send from a specific user's Gmail. When contact_id or deal_id is provided, an outbound email activity is automatically logged to their CRM timeline. If a contact_id / deal_id / customer_id is provided but does not exist in the workspace, the request is rejected with 400 VALIDATION_ERROR before the email is dispatched; the response body includes details.missing_entities with the offending field names and IDs. Omit the field entirely to send without a CRM link. Rare: if the email is delivered but the internal log row fails, the API returns 422 EMAIL_LOG_FAILED with the delivery message id in message_id so the caller knows the email did reach the recipient.

**Scopes:** `email:send` — [full detail](./email/post-email-send.md)

### POST /email/reply

Reply to an existing email thread. Default mode is "company" (uses configured provider). Use mode "personal" with sender_user_id for a user's Gmail.

**Scopes:** `email:send` — [full detail](./email/post-email-reply.md)

### GET /email/capabilities

Check email sending capabilities. Returns authenticated_user (the API caller's identity), Company Mail provider (TrustPager Mail or Gmail), and which users have personal Gmail connected. Use authenticated_user to identify who "I" is for personal/conversational sends.

**Scopes:** `email:read` — [full detail](./email/get-email-capabilities.md)

### GET /email/logs

List email send logs. Each log includes subject, recipient_email, sender_email, status, provider, cc, thread_id, and sender_user_id. Filter by status, contact, deal, type, or provider.

**Scopes:** `email:read` — [full detail](./email/get-email-logs.md)

### GET /email/configs

List all email configurations for the company.

**Scopes:** `email:read` — [full detail](./email/get-email-configs.md)

### GET /email/configs/:id

Retrieve a specific email configuration.

**Scopes:** `email:read` — [full detail](./email/get-email-configs-id.md)

### POST /email/configs

Create an email configuration. Requires from_email_handle, from_name, and staff_email. Pass the local-part only as from_email_handle (e.g. "support") -- the server composes the full address as support@mail.trustpager.net. Passing the legacy from_email field returns error code FROM_EMAIL_NOT_WRITABLE. Invalid handles return INVALID_FROM_EMAIL_HANDLE. gmail_sender_alias must already exist as a "Send mail as" address on the connected Gmail account assigned to this workspace (ALIAS_NOT_CONNECTED otherwise). See GET /email/capabilities for available send_as_aliases.

**Scopes:** `email-config:write` — [full detail](./email/post-email-configs.md)

### PATCH /email/configs/:id

Partial update of an email configuration. Same shape validation as POST: pass from_email_handle (local-part only) to change the Postmark sender address; passing from_email returns FROM_EMAIL_NOT_WRITABLE. gmail_sender_alias must be a registered send-as alias for the connected user (ALIAS_NOT_CONNECTED, GMAIL_NOT_CONNECTED, GMAIL_USER_REQUIRED).

**Scopes:** `email-config:write` — [full detail](./email/patch-email-configs-id.md)

### DELETE /email/configs/:id

Delete an email configuration.

**Scopes:** `email-config:write` — [full detail](./email/delete-email-configs-id.md)

### PATCH /email/threads/:id

Update an email thread — mark as read/unread or change status (active, archived, spam).

**Scopes:** `email:write` — [full detail](./email/patch-email-threads-id.md)

### POST /email/threads/mark-read

Bulk mark email threads as read. Use thread_ids for specific threads, or all:true to mark all unread threads read. Returns the count of threads updated.

**Scopes:** `email:write` — [full detail](./email/post-email-threads-mark-read.md)