{
  "name": "email",
  "title": "Email Formatting Guide",
  "description": "Email formatting: HTML style rules, image handling, and deliverability tips",
  "guid": "sk_plat_emgd",
  "category": "Agent Tools",
  "requiredTools": [
    "agent_email_send",
    "gmail_send",
    "gmail_reply",
    "html_preview",
    "host_file"
  ],
  "content": "# Email Formatting Guide\n\n## Plain characters only\nUse 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.\n\n## Two distinct email channels\n\nGipity has two separate email paths. Use the one that matches who the recipient should see as the sender.\n\n| Dimension | Platform email (agent channel) | User's Gmail (user channel) |\n|---|---|---|\n| Agent tool | `agent_email_send` | `gmail_send`, `gmail_reply`, `gmail_search`, `gmail_read` |\n| Web CLI | `/email send` | `/gmail send|reply|search|read` |\n| Local CLI | `gipity email send` | `gipity gmail send|reply|search|read` |\n| Sender address | `gipity@gipity.ai` | the user's own Gmail address |\n| Quota / deliverability | Gipity platform quota | User's Gmail quota |\n| Approval | Required for external recipients; self-sends skip it | Required per connection settings |\n| Requires | Nothing extra | A connected Google OAuth account |\n| 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) |\n\n**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.\n\n- Omit `to` on `agent_email_send` to send to the user's own email (skips approval).\n\n## Replying to a Gmail thread\n- Always `gmail_read` the message you're replying to first - you need its sender, date, and full body to build the quote.\n- 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:\n\n  ```\n  Sounds good - Tuesday at 2pm works for me.\n\n  On Wed, Apr 17, 2026 at 9:14 AM, Alice <alice@example.com> wrote:\n  > Can we move the sync to Tuesday?\n  > Let me know what time works.\n  ```\n\n- 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.\n- Default to including the quote. Skip it only if the user explicitly says so (e.g. \"just send 'yes', don't quote\").\n- For `subject`, prefix the original subject with `Re: ` if it isn't already.\n\n## How agent_email_send works\n- 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.\n- Every email includes an unsubscribe link - recipients can block future emails from the sender.\n- Self-sends (omitting `to` or sending to the user's own email) skip approval.\n- A platform footer is automatically appended to all agent-sent emails.\n\n### Rate Limits\n- **Max 10 emails per 1 hour** per agent\n- Plan batch sends accordingly - space them out if sending to multiple recipients\n\n### Parameters\n- `to` - recipient email (optional; omit for self-send)\n- `subject` - subject line (required)\n- `body` - plain text body (required)\n- `html` - optional HTML body, used as the rich version alongside plain text\n\n## HTML Style Rules\n- **Inline styles only** - email clients strip `<style>` tags. Every element needs `style=\"...\"`.\n- **System fonts**: `font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif`\n- **Single-column layout** - centered `<div>` or `<table>` with `max-width: 600px`. No flexbox/grid.\n- **Minimal colors** - dark text (#333) on white (#fff). One accent color max.\n- **Font sizes**: 14-16px body, 20-24px headings, never below 12px.\n\n## Images\n- **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.\n- **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.\n- **Never SVG** - email clients strip it. Convert to PNG/JPG first: `cairosvg` (Python) or ImageMagick.\n- **Never base64** - email clients strip `data:` URIs. Always `host_file` and link: `<img src=\"https://...\" width=\"...\" height=\"...\">`.\n- **HTML display width**: use `width=\"600\"` (or less) on the `<img>` - 600px is the standard single-column email layout width.\n\n## Preview\n- Preview rich/styled HTML emails with `html_preview` before sending - verify layout and images render correctly.\n- Simple text-only emails don't need a preview step.\n- Same hosted URLs work in both preview and email.\n- 3MB preview limit - compress images in sandbox if needed."
}