Email Formatting Guide — docs.gipity.ai

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
Local CLI	`gipity email send`	`gipity gmail send
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.