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 ada@example.com --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 ada@example.com --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 ada@example.com --subject "v1" --body-file /tmp/a.txt --json
# -> data.draft_id
gmail draft update --draft-id r-8891 --to ada@example.com --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 ada@example.com --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.