Gmail¶

Gmail ¶

Gmail(auth: GoogleAuth, user_id: str = 'me')

High-level Gmail client.

Example

auth = GoogleAuth() auth.authenticate()

gmail = Gmail(auth)

Get unread¶

for msg in gmail.get_unread(): print(msg.subject) msg.mark_as_read()

Send¶

gmail.send( to=["user@example.com"], subject="Hello", body="World", )

Initialize Gmail client.

Parameters:

Name	Type	Description	Default
`auth`	`GoogleAuth`	GoogleAuth instance with valid credentials	required
`user_id`	`str`	Gmail user ID ("me" for authenticated user)	`'me'`

service `property` ¶

service: Any

Lazy-load Gmail API service.

email `property` ¶

email: str

Get authenticated user's email address (fetched once).

iter_messages ¶

iter_messages(query: str | Query | None = None, labels: list[str] | None = None, max_results: int | None = 25, include_body: bool = True) -> Iterator[Message]

Lazily yield messages matching criteria, following result pages.

Messages are fetched in HTTP batches of 50 rather than one request each. A message deleted while listing is skipped.

Parameters:

Name	Type	Description	Default
`query`	`str \| Query \| None`	Gmail search query (str or Query object)	`None`
`labels`	`list[str] \| None`	Filter by label IDs	`None`
`max_results`	`int \| None`	Maximum messages to yield (None = all matches)	`25`
`include_body`	`bool`	Whether to fetch full message content	`True`

get_messages ¶

get_messages(query: str | Query | None = None, labels: list[str] | None = None, max_results: int | None = 25, include_body: bool = True) -> list[Message]

Get messages matching criteria.

Parameters:

Name	Type	Description	Default
`query`	`str \| Query \| None`	Gmail search query (str or Query object)	`None`
`labels`	`list[str] \| None`	Filter by label IDs	`None`
`max_results`	`int \| None`	Maximum messages to return (None = all matches; can be slow)	`25`
`include_body`	`bool`	Whether to fetch full message content	`True`

Returns:

Type	Description
`list[Message]`	List of Message objects

search ¶

search(query: str | Query, max_results: int = 25) -> list[Message]

Search messages with a query.

Parameters:

Name	Type	Description	Default
`query`	`str \| Query`	Gmail search query	required
`max_results`	`int`	Maximum results	`25`

Returns:

Type	Description
`list[Message]`	List of matching messages

get_unread ¶

get_unread(max_results: int = 25) -> list[Message]

Get unread messages.

get_unread_inbox ¶

get_unread_inbox(max_results: int = 25) -> list[Message]

Get unread messages in inbox.

get_starred ¶

get_starred(max_results: int = 25) -> list[Message]

Get starred messages.

get_important ¶

get_important(max_results: int = 25) -> list[Message]

Get important messages.

get_sent ¶

get_sent(max_results: int = 25) -> list[Message]

Get sent messages.

get_drafts ¶

get_drafts(max_results: int = 25) -> list[Message]

Get draft messages (as Messages; see list_drafts for Draft objects).

get_message ¶

get_message(message_id: str) -> Message | None

Get a specific message by ID, or None if it doesn't exist.

get_thread ¶

get_thread(thread_id: str) -> Thread | None

Get a full thread by ID, or None if it doesn't exist.

iter_threads ¶

iter_threads(query: str | Query | None = None, labels: list[str] | None = None, max_results: int | None = 25) -> Iterator[Thread]

Lazily yield conversations matching criteria (fetched in batches).

get_threads ¶

get_threads(query: str | Query | None = None, labels: list[str] | None = None, max_results: int | None = 25) -> list[Thread]

Get conversations matching criteria.

get_labels ¶

get_labels() -> list[Label]

Get all labels, with message and thread counts.

create_label ¶

create_label(name: str, show_in_label_list: bool = True, show_in_message_list: bool = True) -> Label

Create a label. Use "Parent/Child" to nest it.

Returns:

Type	Description
`Label`	The new Label

rename_label ¶

rename_label(label: str, new_name: str) -> Label

Rename a label (by name or ID).

delete_label ¶

delete_label(label: str) -> bool

Delete a label (by name or ID). Messages keep existing, unlabeled.

Returns:

Type	Description
`bool`	True if deleted, False if no such label exists

batch_modify ¶

batch_modify(message_ids: Sequence[str], add_labels: Sequence[str] | None = None, remove_labels: Sequence[str] | None = None) -> int

Add/remove labels on many messages in a few calls (1000 per call).

Labels can be names or IDs ("UNREAD", "STARRED", "INBOX", "Work"). Example: gmail.batch_modify(ids, remove_labels=["UNREAD"]) marks read.

Returns:

Type	Description
`int`	Number of message IDs sent

list_filters ¶

list_filters() -> list[dict]

List filters ({id, criteria, action} dicts as the API returns them).

create_filter ¶

create_filter(criteria: dict, action: dict) -> dict

Create a filter for incoming mail.

Parameters:

Name	Type	Description	Default
`criteria`	`dict`	e.g. {"from": "alerts@example.com", "hasAttachment": True}	required
`action`	`dict`	e.g. {"addLabelIds": ["Alerts"], "removeLabelIds": ["INBOX"]}. Label names are resolved to IDs for you.	required

Returns:

Type	Description
`dict`	The created filter

delete_filter ¶

delete_filter(filter_id: str) -> bool

Delete a filter. Returns False if it doesn't exist.

get_signature ¶

get_signature(send_as_email: str | None = None) -> str | None

Get the account's email signature.

Parameters:

Name	Type	Description	Default
`send_as_email`	`str \| None`	Specific send-as email (default: primary)	`None`

Returns:

Type	Description
`str \| None`	HTML signature or None

send ¶

send(to: list[str], subject: str, body: str, cc: list[str] | None = None, bcc: list[str] | None = None, html: bool = False, signature: bool = False, reply_to: str | None = None, thread_id: str | None = None, attachments: list[OutgoingAttachment] | None = None) -> Message

Send an email.

Parameters:

Name	Type	Description	Default
`to`	`list[str]`	Recipient email addresses	required
`subject`	`str`	Email subject	required
`body`	`str`	Email body	required
`cc`	`list[str] \| None`	CC recipients	`None`
`bcc`	`list[str] \| None`	BCC recipients	`None`
`html`	`bool`	Whether body is HTML (a plain-text alternative is added)	`False`
`signature`	`bool`	Include account signature (appends to body)	`False`
`reply_to`	`str \| None`	Gmail message ID this replies to; sets the threading headers and thread (see reply() for a higher-level version)	`None`
`thread_id`	`str \| None`	Thread ID (for threading)	`None`
`attachments`	`list[OutgoingAttachment] \| None`	File paths or (filename, bytes) tuples	`None`

Returns:

Type	Description
`Message`	The sent message

reply ¶

reply(message: Message, body: str, html: bool = False, signature: bool = False, reply_all: bool = False, attachments: list[OutgoingAttachment] | None = None) -> Message

Reply to a message, in its thread for every participant.

Goes to the Reply-To address (or the sender). Replying to a message you sent goes to its recipients instead of back to you.

Parameters:

Name	Type	Description	Default
`reply_all`	`bool`	Also include the other To/Cc recipients	`False`

Returns:

Type	Description
`Message`	The sent reply

forward ¶

forward(message: Message, to: list[str], body: str = '', include_attachments: bool = True) -> Message

Forward a message, quoting it below body.

Parameters:

Name	Type	Description	Default
`include_attachments`	`bool`	Re-attach the original attachments	`True`

Returns:

Type	Description
`Message`	The sent message

create_draft ¶

create_draft(to: list[str], subject: str, body: str, cc: list[str] | None = None, bcc: list[str] | None = None, html: bool = False, attachments: list[OutgoingAttachment] | None = None, reply_to: str | None = None) -> Draft

Save a draft (same arguments as send()).

get_draft ¶

get_draft(draft_id: str) -> Draft | None

Get a draft, or None if it doesn't exist.

list_drafts ¶

list_drafts(max_results: int | None = 25) -> list[Draft]

List drafts with their content (fetched in batches).

send_draft ¶

send_draft(draft_id: str) -> Message

Send a draft. Returns the sent message.

delete_draft ¶

delete_draft(draft_id: str) -> bool

Discard a draft. Returns False if it doesn't exist.

get_profile ¶

get_profile() -> dict

Get authenticated user's profile.

Message `dataclass` ¶

Message(id: str, thread_id: str, subject: str, sender: str, recipient: str, cc: list[str] = list(), bcc: list[str] = list(), date: datetime | None = None, snippet: str = '', plain: str | None = None, html: str | None = None, labels: list[str] = list(), attachments: list[Attachment] = list(), reply_to: str | None = None, rfc822_message_id: str | None = None, references: str | None = None, _gmail: Optional[Gmail] = None)

Gmail message with fluent modification methods.

Example

message.mark_as_read().star().add_label("Work")

is_unread `property` ¶

is_unread: bool

Check if message is unread.

is_starred `property` ¶

is_starred: bool

Check if message is starred.

is_important `property` ¶

is_important: bool

Check if message is marked important.

body `property` ¶

body: str

Get body content (prefers plain text).

mark_as_read ¶

mark_as_read() -> Message

Mark message as read.

mark_as_unread ¶

mark_as_unread() -> Message

Mark message as unread.

star ¶

star() -> Message

Star the message.

unstar ¶

unstar() -> Message

Remove star from message.

mark_important ¶

mark_important() -> Message

Mark message as important.

mark_not_important ¶

mark_not_important() -> Message

Mark message as not important.

trash ¶

trash() -> Message

Move message to trash.

untrash ¶

untrash() -> Message

Remove message from trash.

archive ¶

archive() -> Message

Archive message (remove from inbox).

move_to_inbox ¶

move_to_inbox() -> Message

Move message to inbox.

add_label ¶

add_label(label_name: str) -> Message

Add a label to the message.

remove_label ¶

remove_label(label_name: str) -> Message

Remove a label from the message.

reply ¶

reply(body: str, html: bool = False, signature: bool = False, reply_all: bool = False, attachments: list | None = None) -> Message

Reply to this message, in the same thread for every participant.

Parameters:

Name	Type	Description	Default
`body`	`str`	Reply body	required
`html`	`bool`	Whether body is HTML	`False`
`signature`	`bool`	Include account signature	`False`
`reply_all`	`bool`	Also reply to the other To/Cc recipients	`False`
`attachments`	`list \| None`	File paths or (filename, bytes) tuples	`None`

Returns:

Type	Description
`Message`	The sent reply message

forward ¶

forward(to: list[str], body: str = '', include_attachments: bool = True) -> Message

Forward this message (with its attachments by default).

Gmail¶

Gmail ¶

Get unread¶

Send¶

service property ¶

email property ¶

iter_messages ¶

get_messages ¶

search ¶

get_unread ¶

get_unread_inbox ¶

get_starred ¶

get_important ¶

get_sent ¶

get_drafts ¶

get_message ¶

get_thread ¶

iter_threads ¶

get_threads ¶

get_labels ¶

create_label ¶

rename_label ¶

delete_label ¶

batch_modify ¶

list_filters ¶

create_filter ¶

delete_filter ¶

get_signature ¶

send ¶

reply ¶

forward ¶

create_draft ¶

get_draft ¶

list_drafts ¶

send_draft ¶

delete_draft ¶

get_profile ¶

Message dataclass ¶

is_unread property ¶

is_starred property ¶

is_important property ¶

body property ¶

mark_as_read ¶

mark_as_unread ¶

star ¶

unstar ¶

mark_important ¶

mark_not_important ¶

trash ¶

untrash ¶

archive ¶

move_to_inbox ¶

add_label ¶

remove_label ¶

reply ¶

forward ¶

service `property` ¶

email `property` ¶

Message `dataclass` ¶

is_unread `property` ¶

is_starred `property` ¶

is_important `property` ¶

body `property` ¶