gmail-draft

name

gmail-draft

description

Prepare Gmail messages without sending them: create, update, list, send, and delete drafts, with attachments. Use when the user asks to draft, prepare, or write up an email, to save something for later, to revise a draft, or to send one they already approved. Prefer this over sending directly whenever the exact wording has not been agreed yet: a draft is reviewable in Gmail and costs nothing to throw away.

gmail-draft

gmail draft create --to <addr> --subject <s> --body-file <file> [--cc][--bcc][--attach]
gmail draft update --draft-id <id> --to <addr> --subject <s> --body-file <file>
gmail draft list [--query "<gmail query>"] [--max 25]
gmail draft send --draft-id <id>
gmail draft delete --draft-id <id>

--json gives the Envelope on any of them.

When to draft instead of send

Draft by default. Send directly only when the user has seen the words and said to send them. Drafting is the whole reason this is a separate skill from gmail-send: it turns an irreversible action into a reviewable one, and the user can finish it in Gmail on their phone.

Reach for a draft when the user says "write", "draft", "prepare", "put together", "start an email"; when the message matters and they have not read it yet; or when you are composing on their behalf from your own understanding of a thread.

Writing the body

Put the body in a file and pass --body-file. --body exists for one-liners, but shell quoting mangles anything with newlines, quotes, or a dollar sign, and you will not notice until it is sent.

cat > /tmp/reply.txt <<'EOF'
Hi Ada,

Tuesday at 10 works. I will send an agenda beforehand.

Hector
EOF
gmail draft create --to [e-mail] --subject "Re: Tuesday" --body-file /tmp/reply.txt

Write in the user's voice, not yours. If you have their previous mail in context, match its register: how they open, how they sign off, how long their sentences are. Do not add pleasantries they never use.

Attachments

gmail draft create --to [e-mail] --subject "CV" \
  --body-file /tmp/note.txt --attach ~/docs/cv.pdf --attach ~/docs/portfolio.pdf

--attach repeats. Paths must exist; the tool does not expand globs, your shell does. The encoded message has to stay under Gmail's 25 MB, which is about 18 MB of actual files because base64 inflates by a third. Over that, it is refused before anything is created.

Revising

update replaces the draft in place, so pass the whole message again, not just the part that changed. Keep the draft id from create.

gmail draft create --to [e-mail] --subject "v1" --body-file /tmp/a.txt --json
# -> data.draft_id
gmail draft update --draft-id r-8891 --to [e-mail] --subject "v2" --body-file /tmp/b.txt

A draft may be incomplete. No recipient and no subject is fine; it is a scratchpad until it is sent.

Sending one

gmail draft send --draft-id r-8891

This is a real send and cannot be undone. Show the user the recipients, subject, and body first and get an explicit go-ahead, even though they asked for the draft earlier: what they approved was the draft existing, not it leaving.

Previewing

--dry-run on create or update builds the exact message and returns the preview without touching the mailbox. Useful to check attachments resolved and the body survived quoting.

gmail draft create --to [e-mail] --subject "CV" --body-file /tmp/note.txt \
  --attach ~/docs/cv.pdf --dry-run

If a command fails, read error.hint; for anything auth-shaped, run gmail doctor.