Gmail Client

This is the full description of the GmailClient class

GmailClient class

class google_workspace.gmail.GmailClient

Create a Gmail client to interact with the Gmail API.

Parameters

service (GoogleService | str, optional) – Pass either a GoogleService instance or the GoogleService session name. If left empty will use “gmail” for session name. If the service is not authenticated, we’ll run local_oauth. Defaults to None.
workers (int, optional) – Number of threads to use when handling updates. Defaults to 4.
save_state (bool, optional) – whether or not to save the state when the application stops, if set to True and the application is then restarted and save_state is still set to True, the app will go back in time to handle the updated that happend while the app was offline. See the limitations here: https://developers.google.com/gmail/api/guides/sync#limitations. Defaults to False.
update_interval (int, optional) – How long to sleep before checking for updates again. Defaults to 1.
email_address (str, optional) – If you dont have enough scopes for getting the user’s info, you have to specify the user’s email address which will be used when sending messages.
sender_name (str, optional) – If you dont have enough scopes for getting the user’s info, you can set the senders name here, and will be used when sending emails.

workers: Number of workers.

save_state: whether to save the history_id.

update_interval: How often to check for updates.

sender_name: The user’s name.

email_address: The user’s email address.

add_handler(handler: Type[google_workspace.gmail.handlers.BaseHandler]) → None

Add a handler.

Parameters: handler (BaseHandler) – The handler you would like to add.

add_labels_to_message(message_id: str, label_ids: Union[list, str]) → dict

Add labels to a message

Parameters

message_id (str) – The message id.
label_ids (list | str) – The labels to add.

Returns

The API response.

Return type

dict

add_labels_to_thread(thread_id: str, label_ids: Union[list, str]) → dict

Add labels to all messages in a thread.

Parameters

thread_id (str) – The thread id.
label_ids (list | str) – The labels to add.

Returns

The API response.

Return type

dict

create_label(name: str, message_list_visibility: Literal[~~'show'~~, ~~'hide'~~] = 'show', label_list_visibility: Literal[~~'labelShow'~~, ~~'labelShowIfUnread'~~, ~~'labelHide'~~] = 'labelShow', background_color: Optional[str] = None, text_color: Optional[str] = None) → google_workspace.gmail.label.Label

Create a label

Parameters

name (str) – The display name of the label.
message_list_visibility (str, optional) – The visibility of messages with this label in the message list in the Gmail web interface. Can have one of the following values: "show", "hide" For more information visit the Gmail API documentation. Defaults to: “show”.
label_list_visibility (str, optional) – The visibility of the label in the label list in the Gmail web interface. Can have one of the following values: "labelShow", "labelShowIfUnread", "labelHide" For more information visit the Gmail API documentation. Defaults to: “labelShow”.
background_color (str, optional) – The background color represented as hex string. Defaults to None.
text_color (str, optional) – The text color of the label, represented as hex string. Defaults to None.

Returns

The created label.

Return type

Label

static decode_pub_sub_message(message: Union[str, bytes]) → dict

Decodes an incoming pub/sub message.

Parameters: message (str | bytes) – The message recived from Google, as text or bytes.
Returns: The actual message like this: {“emailAddress”: “user@example.com”, “historyId”: “9876543210”}
Return type: dict

delete_message(message_id: str) → dict

Delete a message.

Parameters: message_id (str) – The message id.
Returns: The API response.
Return type: dict

delete_thread(thread_id: str) → dict

Delete an entire thread.

Parameters: thread_id (str) – The thread id.
Returns: The API response.
Return type: dict

get_auto_forwarding_settings() → dict

Get auto forwarding settings.

Returns: The API response.
Return type: dict

get_filters() → dict

Get filters.

Returns: The API response.
Return type: dict

get_history(start_history_id: int, label_id: Optional[str] = None, history_types: Optional[Iterable[Literal[~~'messageAdded'~~, ~~'messageDeleted'~~, ~~'labelAdded'~~, ~~'labelRemoved'~~]]] = None, max_results: Optional[int] = None) → google_workspace.gmail.histories.ListHistoryResponse

Get everything that happened in the account since start_history_id.

Parameters

start_history_id (int) – Where to start the results from.
label_id (str, optional) – Only return histories which have the label in thier message.
history_types (str, optional) – Only return histories of this types.
max_results (int, optional) – Maximum number of history records to return. The maximum allowed value for this field is 500.

Returns

A iterable of histories.

Return type

listHistoryResponse

get_imap_settings() → dict

Get imap settings.

Returns: The API response.
Return type: dict

get_label_by_id(label_id: str) → google_workspace.gmail.label.Label

Get a label by it’s id.

Parameters: label_id (str) – The label id.
Returns: The label.
Return type: Label

get_lables() → Generator[google_workspace.gmail.label.Label, None, None]

Get all Labels.

Returns: A generator of all the labels.
Return type: Generator of Label

get_language_settings() → dict

Get language settings.

Returns: The API response.
Return type: dict

get_message_by_id(message_id: str, message_format: Literal[~~'minimal'~~, ~~'full'~~, ~~'raw'~~, ~~'metadata'~~] = 'raw') → Type[google_workspace.gmail.message.BaseMessage]

Get a message by it’s id

Parameters

message_id (str) – The message id. (The gmail_id property)
message_format (str, optional) – In which format to retrieve the messages. Can have one of the following values: "minimal", "full", "raw", "metadata". Defaults to “raw”.

Returns

Depending message_format it will return a differenttype of message.

Return type

Message | MessageMetadata | MessageMinimal

get_messages(label_ids: Optional[Union[list, str]] = None, seen: Optional[bool] = None, from_: Optional[str] = None, to: Optional[list] = None, subject: Optional[str] = None, after: Optional[datetime.date] = None, before: Optional[datetime.date] = None, label_name: Optional[str] = None, include_spam_and_trash: bool = False, message_format: Literal[~~'minimal'~~, ~~'full'~~, ~~'raw'~~, ~~'metadata'~~] = 'raw', batch: bool = True, limit: Optional[int] = None) → Generator[Type[google_workspace.gmail.message.BaseMessage], None, None]

Search and get messages

Parameters

label_ids (list | str, optional) – Get only messages that have all these labels. Defaults to None.
seen (bool, optional) – Get only seen or unseen messages. Defaults to None.
from (str, optional) – Get only messages from this sender. Defaults to None.
to (list, optional) – Get only messages that where sent to this list of recipients. Defaults to None.
subject (str, optional) – Get only messages that have this subject. Defaults to None.
after (date, optional) – Get only messages that where send after this date. Defaults to None.
before (date, optional) – Get only messages that where sent before this date. Defaults to None.
label_name (str, optional) – Get only messages that have this label. differs from label_ids that this take the lable name, not the id. Defaults to None.
include_spam_and_trash (bool, optional) – Whether to include spam and trash in the results. Defaults to False.
message_format (str, optional) – In which format to retrieve the messages. Can have one of the following values: "minimal", "full", "raw", "metadata". Defaults to “raw”.
batch (bool, optional) – Whether to use batch requests when fetching the messages. recommended when fetching a lot of messages. Defaults to True.
limit (int, optional) – Limit the number of messages to retrieve. especially useful when batch is True to avoid downloading more messages then you need. Defaults to None.

Returns

Depending message_format it will return a differenttype of message.

Return type

Generator of Message | MessageMetadata | MessageMinimal

get_pop_settings() → dict

Get pop settings.

Returns: The API response.
Return type: dict

get_thread_by_id(thread_id: str, message_format: Literal[~~'minimal'~~, ~~'full'~~, ~~'metadata'~~] = 'full') → google_workspace.gmail.thread.Thread

Get a thread by it’s id

Parameters

thread_id (str) – The thread id.
message_format (str, optional) – In which format to retrieve the messages. Can have one of the following values: "minimal", "full", "metadata". Defaults to “full”.

Returns

The full thread with all it’s messages.

Return type

Thread

get_threads(label_ids: Optional[Union[list, str]] = None, seen: Optional[bool] = None, from_: Optional[str] = None, to: Optional[list] = None, subject: Optional[str] = None, after: Optional[datetime.date] = None, before: Optional[datetime.date] = None, label_name: Optional[str] = None, include_spam_and_trash: bool = False, message_format: Literal[~~'minimal'~~, ~~'full'~~, ~~'metadata'~~] = 'full', batch: bool = True, limit: Optional[int] = None) → Generator[google_workspace.gmail.thread.Thread, None, None]

Search and get threads

Parameters

label_ids (list | str, optional) – Get only threads that have all these labels. Defaults to None.
seen (bool, optional) – Get only seen or unseen threads. Defaults to None.
from (str, optional) – Get only threads from this sender. Defaults to None.
to (list, optional) – Get only threads that where sent to this list of recipients. Defaults to None.
subject (str, optional) – Get only threads that have this subject. Defaults to None.
after (date, optional) – Get only threads that where send after this date. Defaults to None.
before (date, optional) – Get only threads that where sent before this date. Defaults to None.
label_name (str, optional) – Get only threads that have this label. differs from label_ids that this take the lable name, not the id. Defaults to None.
include_spam_and_trash (bool, optional) – Whether to include spam and trash in the results. Defaults to False.
message_format (str, optional) – In which format to retrieve the messages. Can have one of the following values: "minimal", "full", "metadata". Defaults to “full”.
batch (bool, optional) – Whether to use batch requests when fetching the threads. recommended when fetching a lot of threads. Defaults to True.
limit (int, optional) – Limit the number of threads to retrieve. especially useful when batch is True to avoid downloading more threads then you need. Defaults to None.

Returns

A generator of all the threads the matched you query.

Return type

Generator of Thread

get_updates() → None: This is the main function which looks for updates on the account, and adds it to the queue.

get_vacation_settings() → dict

Get vacation settings.

Returns: The API response.
Return type: dict

mark_message_as_read(message_id: str) → dict

Mark a message as read.

Parameters: message_id (str) – The message id.
Returns: The API response.
Return type: dict

mark_message_as_unread(message_id: str) → dict

Mark a message as unread.

Parameters: message_id (str) – The message id.
Returns: The API response.
Return type: dict

on_message(func: Optional[Callable[[google_workspace.gmail.histories.History], Any]] = None, labels: Union[list, str] = 'inbox', filters: Optional[Iterable[Callable[[google_workspace.gmail.histories.History], bool]]] = None)

Helper decorator to add a MessageAddedHandler handler.

Parameters

labels – (list | str, optional): Filter for messages that that have these lables. Defaults to "inbox".
filters (list, optional) – A list of filters. A filter is a function that takes in a message as an argument and returns True or False. Defaults to False.

remove_labels_from_message(message_id: str, label_ids: Union[list, str]) → dict

Remove labels from a message.

Parameters

message_id (str) – The message id.
label_ids (list | str) – The labels to remove.

Returns

The API response.

Return type

dict

remove_labels_from_thread(thread_id: str, label_ids: Union[list, str]) → dict

Remove labels from all messages in thread.

Parameters

thread_id (str) – The thread id.
label_ids (list | str) – The labels to remove.

Returns

The API response.

Return type

dict

run() → None: Check for updates and have the handers handle it.

send_message(to: Optional[Union[list, str]] = None, subject: str = '', text: Optional[str] = None, html: Optional[str] = None, attachments: Union[Iterable[str], Iterable[Tuple[bytes, str]]] = [], cc: Optional[Union[list, str]] = None, bcc: Optional[Union[list, str]] = None, references: Optional[str] = None, in_reply_to: Optional[str] = None, thread_id: Optional[str] = None, headers: Optional[dict] = None) → dict

Send a message.

Parameters

to (list | str, optional) – Who to send the message to. Can be either a string or a list of strings. Defaults to None.
subject (str, optional) – The message subject. Defaults to “”.
text (str, optional) – The plain text of the message. if you only specify html the text will be automaticly generated. Defaults to None.
html (str, optional) – The html of the message. Defaults to None.
attachments (list, optional) – A List of attachments. Can be a list of file paths like this [“image.png”, “doc.pdf”], or it can be a list of lists where every list consists of the attachment data and a name for the attachment like this [[b”some binary here”, “image.png”]]. Defaults to [].
cc (list | str, optional) – The cc recipients. Defaults to None.
bcc (list | str, optional) – The bcc recipients. Defaults to None.
references (str, optional) – Message references, used for replies. Defaults to None.
in_reply_to (str, optional) – The message this replies to. Defaults to None.
thread_id (str, optional) – The thread id of the message you are replying to. Defaults to None.
headers (dict, optional) – Additional headers to add to the message. Defaults to None.

Returns

The API response.

Return type

dict

stop() → dict

Stop receiving push notifications for the given user mailbox.

Returns: The API response.
Return type: dict

trash_message(message_id: str) → dict

Trash a message.

Parameters: message_id (str) – The message id.
Returns: The API response.
Return type: dict

trash_thread(thread_id: str) → dict

Trash an entire thread.

Parameters: thread_id (str) – The thread id.
Returns: The API response.
Return type: dict

untarsh_thread(thread_id: str) → dict

Untrash a thread.

Parameters: thread_id (str) – The thread id.
Returns: The API response.
Return type: dict

untrash_message(message_id: str) → dict

Untrash a message.

Parameters: message_id (str) – The message id.
Returns: The API response.
Return type: dict

update_auto_forwarding_settings(enabled: bool, email_address: str, disposition: Literal[~~'dispositionUnspecified'~~, ~~'leaveInInbox'~~, ~~'archive'~~, ~~'trash'~~, ~~'markRead'~~]) → dict

Update auto forwarding settings. This method is only available to service account clients that have been delegated domain-wide authority.

Parameters

enabled (bool) – Whether all incoming mail is automatically forwarded to another address.
email_address (str) – Email address to which all incoming messages are forwarded. This email address must be a verified member of the forwarding addresses.
disposition (str) – The state that a message should be left in after it has been forwarded. Can have one of the following values: "dispositionUnspecified", "leaveInInbox", "archive", "trash", "markRead". For more information visit the Gmail API documentation.

Returns

The API response.

Return type

dict

update_imap_settings(enabled: bool, auto_expunge: bool, expunge_behavior: Literal[~~'expungeBehaviorUnspecified'~~, ~~'archive'~~, ~~'trash'~~, ~~'deleteForever'~~], max_folder_size: int) → dict

Update IMAP settings.

Parameters

enabled (bool) – Whether IMAP is enabled for the account.
auto_expunge (bool) – If this value is true, Gmail will immediately expunge a message when it is marked as deleted in IMAP. Otherwise, Gmail will wait for an update from the client before expunging messages marked as deleted.
expunge_behavior (str) – The action that will be executed on a message when it is marked as deleted and expunged from the last visible IMAP folder. Can have one of the following values: "expungeBehaviorUnspecified", "archive", "trash", "deleteForever" For more information visit the Gmail API documentation.
max_folder_size (int) – An optional limit on the number of messages that an IMAP folder may contain. Legal values are 0, 1000, 2000, 5000 or 10000. A value of zero is interpreted to mean that there is no limit.

Returns

The API response.

Return type

dict

update_language_settings(display_language: str) → dict

Updates language settings.

Parameters: display_language (str) – The language to display Gmail in, formatted as an RFC 3066 Language Tag (for example en-GB, fr or ja for British English, French, or Japanese respectively).
Returns: The API response.
Return type: dict

update_pop_settings(access_window: Literal[~~'accessWindowUnspecified'~~, ~~'disabled'~~, ~~'fromNowOn'~~, ~~'allMail'~~], disposition: Literal[~~'dispositionUnspecified'~~, ~~'leaveInInbox'~~, ~~'archive'~~, ~~'trash'~~, ~~'markRead'~~]) → dict

Updates POP settings.

Parameters

access_window (str) – The range of messages which are accessible via POP. Can have one of the following values: "accessWindowUnspecified", "disabled", "fromNowOn", "allMail" For more information visit the Gmail API documentation.
disposition (str) – The action that will be executed on a message after it has been fetched via POP. Can have one of the following values: "dispositionUnspecified", "leaveInInbox", "archive", "trash", "markRead" For more information visit the Gmail API documentation.

Returns

The API response.

Return type

dict

update_vacation_settings(enable_auto_reply: bool, response_subject: str, response_body_plain_text: str, response_body_html: str, restrict_to_contacts: bool, restrict_to_domain: bool, start_time: int, end_time: int) → dict

Updates vacation responder settings.

Parameters

enable_auto_reply (bool) – Flag that controls whether Gmail automatically replies to messages.
response_subject (str) – Optional text to prepend to the subject line in vacation responses. In order to enable auto-replies, either the response subject or the response body must be nonempty.
response_body_plain_text (str) – Response body in plain text format. If both response_body_plain_text and response_body_html are specified, response_body_html will be used.
response_body_html (str) – Response body in HTML format. Gmail will sanitize the HTML before storing it. If both response_body_plain_text and response_body_html are specified, response_body_html will be used.
restrict_to_contacts (bool) – Flag that determines whether responses are sent to recipients who are not in the user’s list of contacts.
restrict_to_domain (bool) – Flag that determines whether responses are sent to recipients who are outside of the user’s domain. This feature is only available for G Suite users.
start_time (int) – An optional start time for sending auto-replies (epoch ms). When this is specified, Gmail will automatically reply only to messages that it receives after the start time. If both startTime and endTime are specified, startTime must precede endTime.
end_time (int) – An optional end time for sending auto-replies (epoch ms). When this is specified, Gmail will automatically reply only to messages that it receives before the end time. If both startTime and endTime are specified, startTime must precede endTime.

Returns

The API response.

Return type

dict

watch(topic_name: str, label_filter_action: Optional[Literal[~~'include'~~, ~~'exclude'~~]] = None, label_ids: Optional[Union[list, str]] = None) → dict

Set up or update a push notification watch on the given user mailbox.

Parameters

topic_name (str) – A fully qualified Google Cloud Pub/Sub API topic name to publish the events to.
label_filter_action (str, optional) – Filtering behavior of labelIds list specified. Can have one of the following values: "include", "exclude". Defaults to: None.
label_ids (list | str, optional) – List of labelIds to restrict notifications about. By default, if unspecified, all changes are pushed out. If specified then dictates which labels are required for a push notification to be generated. Defaults to: None.

Returns

The API response.

Return type

dict