gmail send: Add --signature flag to append Gmail signature

[kesslerio]

Problem

When sending emails programmatically via gog gmail send, there's no way to include the user's Gmail signature. This means emails sent by AI agents/scripts look different from emails sent via Gmail UI, which can appear unprofessional or inconsistent.

Proposed Solution

Add a --signature flag that appends the user's Gmail signature to outgoing emails.

Options:

1. --signature (no value) - Fetch and append the user's default Gmail signature from Gmail API
2. --signature=<name> - Fetch a specific named signature (Gmail supports multiple)
3. --signature-file=<path> - Append signature from a local file (for offline/custom signatures)

Gmail API Reference

Signatures are stored in users.settings.sendAs resource:

GET https://gmail.googleapis.com/gmail/v1/users/me/settings/sendAs/{sendAsEmail}

Response includes signature field (HTML string).

LLM Implementation Prompt

Add a --signature flag to the gmail send command in gog.

Requirements:
1. Add three new flags to gmail send:
   - --signature (bool): When true, fetch the default signature from Gmail API and append to email body
   - --signature-name (string): Fetch a specific named signature from send-as aliases
   - --signature-file (string): Read signature from local file path

2. Signature fetching logic:
   - Call Gmail API: GET /gmail/v1/users/me/settings/sendAs/{fromEmail}
   - Extract the "signature" field (HTML string)
   - If --body is used (plain text), convert HTML signature to plain text before appending
   - If --body-html is used, append HTML signature directly

3. Signature insertion:
   - Add two newlines before signature
   - For plain text: prepend with "--\n" (standard email signature delimiter)
   - For HTML: wrap in <div class="gmail_signature"> for consistency

4. Error handling:
   - If signature is empty/not set, warn but don't fail
   - If --signature-file path doesn't exist, error with clear message

5. Update help text to document the new flags

Files to modify:
- cmd/gmail/send.go (add flags and logic)
- pkg/gmail/client.go (add GetSignature method if needed)

Use Case

AI agents sending emails on behalf of users need signature parity with manual emails. Currently I have to either:

• Skip signatures (looks incomplete)
• Hardcode signatures in prompts (maintenance burden, gets stale)
• Manually fetch from a sent email and append (tedious)

Priority

Medium - quality of life improvement for automation workflows

[alexisperumal]

+1 — independently hit this on 2026-04-21 building an agentic deployment where multiple agents each needed their own server-side signature to prevent prompt-level identity drift ("Sage signed as Ada").

Empirical confirmation that sendas.signature is NOT auto-applied by gog gmail send (Gmail API messages.send):

1. Set server-side signature via existing gog capability:

   gog gmail settings sendas update <bot>@example.com --signature '<p>Best,<br>Ada</p>'
   

   Verified via sendas get — signature present in the API response.

2. Sent a test email via gog gmail send --body-html '<p>...no signature here...</p>'

3. Inspected the transmitted MIME body via gog gmail get <msgId> --format full --json. Body was exactly what was passed to --body-html, with no signature appended.

So the proposed --signature flag (Option 1 in the issue) would be the right bridge — fetch at send time from users.settings.sendAs.signature and append client-side, since the Gmail API itself doesn't do it on messages.send. --signature-file (Option 3) would also be nice for environments where the signature is managed in source (infra-as-code style), separately from per-mailbox Gmail settings.

Use case for context: OpenClaw-based deployment running three agent containers, each bound to a distinct Google Workspace bot account. Every LLM-generated email needs a stable sign-off that can't drift via prompt contamination. Today we work around this by making each cron prompt read a workspace signoff file and use its literal HTML at the end — reliable but fragile on LLM discipline. Server-side signature managed by gog gmail settings sendas update is already a supported write; exposing it at gog gmail send time would close the loop.

Happy to beta test when this ships.

[steipete]

Implemented on main in 77a16d1. This adds gmail send --signature, --signature-from, and --signature-file, with Gmail send-as lookup plus local plain-text/HTML signature support.

Covered by focused tests in internal/cmd/gmail_send_signature_test.go and documented in README.md, docs/spec.md, and CHANGELOG.md. Closing this as fixed.