kings mail sends Gmail messages with attachments and downloads attachments, from the terminal or
from an AI agent. It exists because email connectors usually can't attach a local file (a CV, a
report): this command can.
| Command | What it does |
|---|---|
kings mail send --to <addr> --subject "<s>" --body <file> [options] |
Sends the message and prints sent <message id> thread <thread id> |
kings mail attachments --thread <id> | --message <id> --out <dir> [--filter <text>] |
Saves the attachments of one message, or of every message in a thread, and prints each path |
kings mail auth [--client <client_secret.json>] |
Authorizes the account in the browser; --client stores the OAuth client first |
kings mail status |
Configured account, whether the OAuth client is stored, whether the token is valid |
send options:
| Option | Meaning |
|---|---|
--to, --cc, --bcc |
Recipients; repeat the flag for several |
--body <file> |
.html/.htm goes as HTML with a plain-text part; any other file goes as text; - reads text from stdin |
--attach <file> |
Attachment; repeat for several (25 MB in total, Gmail's limit) |
--thread <id> |
Reply inside this thread. The subject must be the thread's, with Re: |
--in-reply-to <Message-ID> |
The answered message's Message-ID header, so the recipient's client threads it too |
--draft |
Leave it as a draft in Gmail instead of sending; prints draft <id> thread <id> |
kings mail send --to recruiter@company.com --subject "iOS Developer - Jane Doe" \
--body ~/mail/application.html --attach ~/CV/JaneDoe_CV.pdf
kings mail attachments --thread 19ce8fc963b19e91 --out ~/Downloads/contract --filter .pdfThe summary (from, to, subject, attachments) goes to stderr before anything is sent, so it lands in the log and in an agent's transcript.
Once per machine. You need a Google account and about 10 minutes.
In ~/.kingsScripts/config.env:
KINGS_MAIL_ACCOUNT="you@gmail.com" # the only account the command acts as
KINGS_MAIL_NAME="Your Name" # sender name shown to recipientsAt console.cloud.google.com, signed in with that account:
- Create a project (any name).
- APIs & Services → Library: enable the Gmail API.
- Google Auth Platform → Branding: user type External; app name and contact emails.
- Audience: add your address as a test user.
- Data Access: add the scopes
https://www.googleapis.com/auth/gmail.composeandhttps://www.googleapis.com/auth/gmail.readonly. - Clients → Create client: type Desktop app; download the JSON.
kings mail auth --client ~/Downloads/client_secret_XXXX.json- The first run creates a Python environment in
~/.kingsScripts/venvs/mail(needspython3). - The browser opens: pick the configured account. "Google hasn't verified this app" is expected for your own app: Continue.
- The client and the token go to the Keychain. Delete the downloaded JSON afterwards.
kings mail statusconfirms it.
An app left in Testing gets refresh tokens that Google expires after 7 days. The next command after that opens the browser again; one click and it continues. Publishing the app removes the limit but asks for a home page and a privacy policy on a verified domain, which rarely pays off for personal use.
| Piece | Role |
|---|---|
mail.sh |
Checks the subcommand, keeps the virtualenv in sync with requirements.txt, runs gmail.py |
gmail.py |
Gmail API: builds the MIME message, sends through a draft, reads attachments |
requirements.txt |
google-api-python-client, google-auth-oauthlib, keyring |
- Sending goes through a draft (
drafts.create, thendrafts.send): the same path serves--draft, and a reply with--threadlands in the thread in both modes. - Account check: every run compares the signed-in address with
KINGS_MAIL_ACCOUNT. A token for another account is dropped and the command stops.
- No secret in a file. The OAuth client and the token live in the macOS Keychain, service
kings, accountsKINGS_MAIL_CLIENTandKINGS_MAIL_TOKEN— the same store askings secret. An environment variable with that name wins, as insecret_get. - Scopes:
gmail.composecreates drafts and sends;gmail.readonlyreads messages forattachments. Nothing deletes, archives or changes labels. - Revoke: myaccount.google.com/permissions, then
kings secret delete KINGS_MAIL_TOKEN. - An agent should send only what its user approved: the command sends right away, so the approval
belongs before the call (or use
--draftand let the user send from Gmail).