Account - dylandoamaral/ggmail GitHub Wiki

What is an account ?

An Account is the main entry of GGmail.

Authentification methods

Authentication using Google

You can log in to your Gmail account using your username and your password.

:warning: you have to allow less secure applications at https://myaccount.google.com/lesssecureapps to be able to interact with your gmail account.

from ggmail import Account, Google

authentication = Google(username="[email protected]", password="secret")
account = Account(authentication=authentication)

Authentication using GoogleOAuth2

It is more secure to authenticate using an access token provided by google using oauth2. To get this access token, you can check https://developers.google.com/identity/protocols/oauth2.

from ggmail import Account, GoogleOAuth2

authentication = GoogleOAuth2(username="[email protected]", token="secret")
account = Account(authentication=authentication)

Here is a very simple example using google-auth and google_auth_oauthlib libraries:

from ggmail import Account, GoogleOAuth2
from google.oauth2.credentials import Credentials
from google_auth_oauthlib.flow import InstalledAppFlow

scopes = ["https://mail.google.com/"]

flow = InstalledAppFlow.from_client_secrets_file("credentials.json", scopes)
creds = flow.run_local_server(port=0)

authentication = GoogleOAuth2(username="[email protected]", token=creds.token)
account = Account(authentication=authentication)
with account:
    # Do stuff

Authentication using Outlook

You can log in to your Outlook account using your username and your password.

from ggmail import Account, Outlook

authentication = Outlook(username="[email protected]", password="secret")
account = Account(authentication=authentication)

Manage the account session

The first time you want to interact with your email account, you will have to create an Account object. You will then have to create a session. GGmail provides two ways to manage such a session.

Using login/logout

You can manage a session using Account.login and Account.logout, you will be able to interact with your gmail account between the two instructions.

from ggmail import Account, Google

authentication = Google(username="[email protected]", password="secret")
account = Account(authentication=authentication)
account.login()
# Do stuff with it
account.logout()

Using context manager

You can manage a session using python context manager. It is syntactic sugar that will safely close the session when you are done with it.

from ggmail import Account, Google

authentication = Google(username="[email protected]", password="secret")
with Account(authentication=authentication) as account:
  # Do stuff with it

Fetch mailboxes

By default, GGmail will not fetch your mailboxes when you login. However it will, if you attempt to get a mailbox.

You have several ways to get a mailbox, the best ways to retrieve your target mailbox are:

mailboxes = account.mailboxes() # Retrieve all mailboxes
mailboxes = account.customs() # Retrieve all mailboxes that you created

mailbox = account.inbox() # Retrieve your inbox mailbox
mailbox = account.trash() # Retrieve your trash mailbox
mailbox = account.drafts() # Retrieve your mailbox containing draft messages
mailbox = account.important() # Retrieve your mailbox containing important messages based on google algorithm
mailbox = account.sent() # Retrieve your mailbox containing sent messages
mailbox = account.no_select() # Retrieve your mailbox containing no_select messages
mailbox = account.flagged() # Retrieve your mailbox containing starred messages
mailbox = account.all_() # Retrieve your mailbox containing all messages
mailbox = account.junk() # Retrieve your mailbox containing junk messages

Create mailbox

You can create a new custom mailbox providing the path.

mailbox = account.create_mailbox("Parent/MyCustomMailbox")

Delete mailbox

You can delete a custom mailbox either providing a mailbox instance or a path.

mailbox = account.mailbox_from_path("Parent/MyCustomMailbox")
account.delete_mailbox(mailbox)
# Or
account.delete_mailbox_from_path("Parent/MyCustomMailbox")