client¶

Gmail API List and Batch Utilities

This module provides utilities for paginating Gmail API list operations and efficiently retrieving multiple messages or threads using batch requests. It abstracts page token handling and batch processing, offering unified iterator and batch interfaces for different Gmail API endpoints.

pythonic_gmail.client.pagi_list_messages(gmail: GmailResource, kwargs: dict[str, Any] | None = None, page_size: int = 100, max_items: int = 1000) → ListMessagesResponseIterProxy[source]¶

Paginate Gmail messages list with automatic token handling.

Returns an iterator proxy that yields Gmail API responses containing batches of messages. The proxy supports both response-level iteration and individual message iteration through the iter_items() method.

Parameters:

gmail – Gmail API client resource
kwargs – Parameters for Gmail’s messages.list API call
page_size – Number of messages per API request (maxResults)
max_items – Maximum total messages to return across all pages

Returns:

Iterator proxy that yields ListMessagesResponse objects

Examples:

Iterate over API responses:

iterproxy = pagi_list_messages(
    gmail_client,
    kwargs={"userId": "me"},
    page_size=2,
    max_items=6
)
for i, res in enumerate(iterproxy):
    print(f"Response {i}: {res}")

Iterate over individual messages:

iterproxy = pagi_list_messages(
    gmail_client,
    kwargs={"userId": "me"},
    page_size=2,
    max_items=6
)
for i, msg in enumerate(iterproxy.iter_items()):
    print(f"Message {i}: {msg.id}")

Note

This function returns message metadata only (ID and threadId). Use batch_get_messages() to retrieve full message content.

See also

pagi_list_threads() for thread pagination and batch_get_messages() for retrieving full message content.

pythonic_gmail.client.pagi_list_threads(gmail: GmailResource, kwargs: dict[str, Any] | None = None, page_size: int = 100, max_items: int = 1000) → ListThreadsResponseIterProxy[source]¶

Paginate Gmail threads list with automatic token handling.

Returns an iterator proxy that yields Gmail API responses containing batches of threads. The proxy supports both response-level iteration and individual thread iteration through the iter_items() method.

Parameters:

gmail – Gmail API client resource
kwargs – Parameters for Gmail’s threads.list API call
page_size – Number of threads per API request (maxResults)
max_items – Maximum total threads to return across all pages

Returns:

Iterator proxy that yields ListThreadsResponse objects

Examples:

Iterate over API responses:

iterproxy = pagi_list_threads(
    gmail_client,
    kwargs={"userId": "me"},
    page_size=2,
    max_items=6
)
for i, res in enumerate(iterproxy):
    print(f"Response {i}: {res}")

Iterate over individual threads:

iterproxy = pagi_list_threads(
    gmail_client,
    kwargs={"userId": "me"},
    page_size=2,
    max_items=6
)
for i, thread in enumerate(iterproxy.iter_items()):
    print(f"Thread {i}: {thread.id}")

Note

This function returns thread metadata only (ID and snippet). Use batch_get_threads() to retrieve full thread content.

See also

pagi_list_messages() for message pagination and batch_get_threads() for retrieving full thread content.

pythonic_gmail.client.batch_get_messages(gmail: GmailResource, ids: list[str], batch_size: int = 100, kwargs: dict[str, Any] | None = None) → list[Message][source]¶

Retrieve multiple Gmail messages using batch requests.

Efficiently fetches multiple messages by batching API calls, reducing the number of HTTP requests compared to individual get operations. Useful for retrieving full message content after obtaining IDs from pagination functions.

Parameters:

gmail – Gmail API client resource
ids – List of message IDs to retrieve
batch_size – Number of messages to fetch per batch request
kwargs – Additional parameters for Gmail’s messages.get API call

Returns:

List of Message objects

Examples:

Basic message retrieval:

ids = [
    "19959e8dc4ed58dc",
    "199599553c319566",
    "199598bcc7491337",
]
messages = batch_get_messages(
    gmail_client,
    ids=ids,
    batch_size=2,
    kwargs={"userId": "me", "format": "minimal"}
)
for i, msg in enumerate(messages):
    print(f"Message {i}: {msg}")

Note

Uses Gmail’s batch API for efficient retrieval. See batch guide for more details.

See also

pagi_list_messages() for obtaining message IDs and batch_get_threads() for retrieving threads.

pythonic_gmail.client.batch_get_threads(gmail: GmailResource, ids: list[str], batch_size: int = 100, kwargs: dict[str, Any] | None = None) → list[Message][source]¶

Retrieve multiple Gmail threads using batch requests.

Efficiently fetches multiple threads by batching API calls, reducing the number of HTTP requests compared to individual get operations. Useful for retrieving full thread content after obtaining IDs from pagination functions.

Parameters:

gmail – Gmail API client resource
ids – List of thread IDs to retrieve
batch_size – Number of threads to fetch per batch request
kwargs – Additional parameters for Gmail’s threads.get API call

Returns:

List of thread objects (currently typed as Message)

Examples:

Basic thread retrieval:

ids = [
    "199599553c319566",
    "199598bcc7491337",
    "1995984aaf02e9ff",
]
threads = batch_get_threads(
    gmail_client,
    ids=ids,
    batch_size=2,
    kwargs={"userId": "me", "format": "minimal"}
)
for i, thread in enumerate(threads):
    print(f"Thread {i}: {thread}")

Note

Uses Gmail’s batch API for efficient retrieval. See batch guide for more details.

See also

pagi_list_threads() for obtaining thread IDs and batch_get_messages() for retrieving messages.