# POST /email/send

**Resource:** [Email](./email.md)  
**Scopes:** `email:send`  
**Write operation:** yes

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.

## Parameters

| Name | In | Type | Required | Description |
|------|----|------|----------|-------------|
| `to_email` | body | string | yes | Recipient email address |
| `to_name` | body | string | no | Recipient name |
| `subject` | body | string | yes | Email subject |
| `html_body` | body | string | yes | HTML email body |
| `mode` | body | string | no | Send mode: "company" (default) or "personal" |
| `sender_user_id` | body | uuid | no | User UUID whose Gmail to send from (required when mode is "personal") |
| `from_email` | body | string | no | Send-as alias when mode is "personal". Must be a valid alias for the sender (use GET /email/capabilities to see available aliases). If omitted, auto-resolves to the user's workspace email if it is a valid alias. |
| `contact_id` | body | uuid | no | Link to contact. Auto-logs an outbound email activity on the contact timeline. Must exist in this workspace or the request returns 400 VALIDATION_ERROR. |
| `deal_id` | body | uuid | no | Link to deal. Auto-logs an outbound email activity on the deal timeline. Must exist in this workspace or the request returns 400 VALIDATION_ERROR. |
| `cc` | body | string | no | CC recipients as comma-separated email addresses (e.g. "alice@example.com, bob@example.com"). Supported on both mode="company" (TrustPager Mail) and mode="personal" (Gmail). CC addresses are merged into the email thread's participant list. |
| `customer_id` | body | uuid | no | Link to customer. Must exist in this workspace or the request returns 400 VALIDATION_ERROR. |
| `email_config_id` | body | uuid | no | Email config to use (defaults to company default) |
| `attachments` | body | array | no | File attachments (Gmail only, max 25MB total). Array of objects with filename, mime_type, and content (base64-encoded file data). |

## Request example

```bash
curl -X POST \
  "https://api.trustpager.com/functions/v1/api/v1/email/send" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to_email": "client@example.com",
    "to_name": "Jane Doe",
    "subject": "Your CRM Setup Report",
    "html_body": "<h1>Hello!</h1><p>See attached report.</p>",
    "mode": "personal",
    "sender_user_id": "user-uuid-...",
    "attachments": [
      {
        "filename": "report.pdf",
        "mime_type": "application/pdf",
        "content": "JVBERi0xLjQg... (base64-encoded file)"
      }
    ]
  }'
```

---
Base URL: `https://api.trustpager.com/functions/v1/api/v1` — Auth: `Authorization: Bearer YOUR_API_KEY`