# Email Formatting Guide

## Plain characters only
Use plain ASCII characters only. No em dashes, en dashes, smart/curly quotes, ellipsis, non-breaking spaces, or other fancy Unicode punctuation. Use a hyphen (-), straight double quote ("), straight apostrophe ('), and three periods (...). Applies to everything you write for the user: chat responses, email drafts and bodies, file content, memory, commit messages, code comments. Exception: if the user explicitly asks for specific characters or a particular style (for example "use em dashes in this poem", "make it fancy"), follow their lead - they are in charge of their own content.

## Two distinct email channels

Gipity has two separate email paths. Use the one that matches who the recipient should see as the sender.

| Dimension | Platform email (agent channel) | User's Gmail (user channel) |
|---|---|---|
| Agent tool | `agent_email_send` | `gmail_send`, `gmail_reply`, `gmail_search`, `gmail_read` |
| Web CLI | `/email send` | `/gmail send|reply|search|read` |
| Local CLI | `gipity email send` | `gipity gmail send|reply|search|read` |
| Sender address | `gipity@gipity.ai` | the user's own Gmail address |
| Quota / deliverability | Gipity platform quota | User's Gmail quota |
| Approval | Required for external recipients; self-sends skip it | Required per connection settings |
| Requires | Nothing extra | A connected Google OAuth account |
| Use when | The platform owns the message (reminders, heartbeat alerts, platform notifications) | The message should come from the user personally (replies to Gmail threads, outreach from their own address) |

**Default is `agent_email_send`.** Only use `gmail_*` when the user explicitly asks to send from their own Gmail, or when you're replying to an existing Gmail thread.

- Omit `to` on `agent_email_send` to send to the user's own email (skips approval).

## Replying to a Gmail thread
- Always `gmail_read` the message you're replying to first - you need its sender, date, and full body to build the quote.
- The `body` you pass to `gmail_reply` MUST be: the new reply text, a blank line, then a standard quote header `On <date>, <sender> wrote:`, then the prior message body line-prefixed with `> `. Example:

  ```
  Sounds good - Tuesday at 2pm works for me.

  On Wed, Apr 17, 2026 at 9:14 AM, Alice <alice@example.com> wrote:
  > Can we move the sync to Tuesday?
  > Let me know what time works.
  ```

- Quote the message you're directly replying to (the most recent one), and leave any quoted chain it already contains intact - don't strip history.
- Default to including the quote. Skip it only if the user explicitly says so (e.g. "just send 'yes', don't quote").
- For `subject`, prefix the original subject with `Re: ` if it isn't already.

## How agent_email_send works
- External sends require user approval (auto-requested by the tool). Do NOT call the tool again for the same email - the system sends automatically after approval.
- Every email includes an unsubscribe link - recipients can block future emails from the sender.
- Self-sends (omitting `to` or sending to the user's own email) skip approval.
- A platform footer is automatically appended to all agent-sent emails.

### Rate Limits
- **Max 10 emails per 1 hour** per agent
- Plan batch sends accordingly - space them out if sending to multiple recipients

### Parameters
- `to` - recipient email (optional; omit for self-send)
- `subject` - subject line (required)
- `body` - plain text body (required)
- `html` - optional HTML body, used as the rich version alongside plain text

## HTML Style Rules
- **Inline styles only** - email clients strip `<style>` tags. Every element needs `style="..."`.
- **System fonts**: `font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif`
- **Single-column layout** - centered `<div>` or `<table>` with `max-width: 600px`. No flexbox/grid.
- **Minimal colors** - dark text (#333) on white (#fff). One accent color max.
- **Font sizes**: 14-16px body, 20-24px headings, never below 12px.

## Images
- **Default: transcode before emailing.** When sending a user-supplied image (photo, screenshot, render), transcode it in the sandbox first: resize to 800px max on any side, convert to JPG at quality 85. `convert input.png -resize '800x800>' -quality 85 output.jpg` (the `>` only shrinks, never enlarges). A 1.6MB phone photo typically drops to ~100–200KB. Then `host_file` the transcoded version and link/embed that.
- **Send the original only if the user asks** - "send the original", "don't compress", "full resolution", etc. If the input is already small and reasonable (`file_info` reports < ~500KB and under ~1200px), you can skip the transcode.
- **Never SVG** - email clients strip it. Convert to PNG/JPG first: `cairosvg` (Python) or ImageMagick.
- **Never base64** - email clients strip `data:` URIs. Always `host_file` and link: `<img src="https://..." width="..." height="...">`.
- **HTML display width**: use `width="600"` (or less) on the `<img>` - 600px is the standard single-column email layout width.

## Preview
- Preview rich/styled HTML emails with `html_preview` before sending - verify layout and images render correctly.
- Simple text-only emails don't need a preview step.
- Same hosted URLs work in both preview and email.
- 3MB preview limit - compress images in sandbox if needed.