gmail_* — Gmail

The Gmail tool namespace (lowercase) — searching with Gmail query syntax, reading messages, sending and drafting, attachments, labels, and the staged-send flow for customer-facing outbound.

The lowercase gmail_* family is the Leif-side Gmail surface: search, read, send, draft, attachments, labels. Search uses Gmail’s native query syntax (from:, subject:, newer_than:, has:attachment, …), which makes it far more precise than substring matching.

Searching & reading

gmail_search_emails

gmail_search_emails(query, include_body=True, max_results=10, page_token=None)

query is Gmail query syntax. Set include_body=False for a lighter list when you only need headers. Paginate with the returned page_token.

gmail_search_emails_batch

gmail_search_emails_batch(query, include_body=True, total_limit=100)

Same search, but auto-paginates until total_limit results — use this instead of hand-rolling a page_token loop when you want “all of them up to N.”

gmail_get_message

gmail_get_message(message_id, include_body=True)

For incident forensics you want the full headers — see M365 Incident Investigation.

gmail_get_recent_emails

gmail_get_recent_emails(days=7, max_results=20, unread_only=False, page_token=None)

A time-windowed pull without composing a query. unread_only=True for the inbox-triage case.

Sending & drafting

The staged-send flow mirrors social_*’s draft → approve → publish pattern. The Gmail API is not contacted until gmail_confirm_send is called.

# 1. Stage — get back a send_id
gmail_stage_send(to, subject, body, html=False, cc=None, bcc=None, reply_to_id=None)

# 2. Review what's pending
gmail_list_staged_sends()

# 3a. Confirm and send
gmail_confirm_send(send_id)

# 3b. Or discard without sending
gmail_discard_staged_send(send_id)

Staged sends survive server restarts (data/gmail_staged_sends.json). Use gmail_list_staged_sends at session start to catch anything left over.

gmail_send_email (direct, use for non-customer-facing)

gmail_send_email(to, subject, body, cc=None, bcc=None, html=False, reply_to_id=None)

to (and cc/bcc) are lists of addresses. Set html=True to send an HTML body. reply_to_id threads the message as a reply to an existing message.

gmail_create_draft

gmail_create_draft(to, subject, body, html=False)

Creates a draft in Gmail (server-side). Unlike gmail_stage_send, this is visible in the Gmail UI immediately.

Attachments & labels

gmail_get_attachment

gmail_get_attachment(message_id, attachment_id, output_path=None)

Downloads an attachment, optionally to output_path. This is the first step of the vendor-email intake pipelines (e.g. Aqua Systems’ monthly CSV) — see Vendor Price List Intake. Mind where output_path lands: to feed a pricing import, the file must end up on nvrbackup, not the Leif host.

gmail_mark_as_read / gmail_get_labels

gmail_mark_as_read(message_id)
gmail_get_labels()