yylizh / momomail

Gmail Client

Momomail

Momomail is a gmail api wrapper. This package aims to provide a more straight forward way to control gmail.

Install

pip install momomail

Generate a client_secret.json file

This project uses Oauth to authenticate google api. You can go to google api page to apply an Oauth ID then download it. The content would be like below

{
    "installed": {
        "client_id": "xxxxxx.apps.googleusercontent.com",
        "project_id": "xxxxxx",
        "auth_uri": "https://accounts.google.com/o/oauth2/auth",
        "token_uri": "https://oauth2.googleapis.com/token",
        "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
        "client_secret": "xxxxxx",
        "redirect_uris": [
            "http://localhost"
        ]
    }
}

GmailClient

We use a GmailClient to control the gmail api. There are two ways to initialize the gmail client.

If you don't know the refresh token of gmail api

Download the Oauth ID json file, rename it to client_secret.json and put it in the current directory

from momomail.gmail.client import GmailClient

client=GmailClient.setup()

The prgram will first check if there is a refresh_token.json file in the current working directory. If not, the program will enter the authenticate process. There will be a url for user to click to authenticate this api. Copy and paste the code to terminal to authenticate and generate a refresh_token.json in the current working directory.

If you have data of client secret and refresh token

from momomail.gmail.client import GmailClient

client=GmailClient(client_secret,refresh_token)

All the client class inherited from GmailClient, so you can initialize a client object using same process.

MessageClient

Message Client deal with batch action on messages, the available methods are listed below:

from momomail.gmail.message import MessageClient
message_client=MessageClient.setup()

• search messages:
  search_message support arguments inputs like gmail web ui: search string, before, after, read or unread, from, to

  messages=message_client.list("twitter")

• get message:
  get_message is used to get detail of a message. The return object is a Message object.

  message:Message=message_client.get_message(id="message_id")

• batch modify:
  batch_modify modify messages' labels

  message_client.batch_modify(ids=["aaa","bbb"],add_label_ids["TEST"],remove_label_ids["SPAM"])

Gmail moves messages into trash can by adding a "TRASH" label. Thus, message client uses this property to make batch trash and batch untrash method.

• batch trash:
  Move messages to trash can

  message_client.batch_trash(ids=["aaa","bbb"])

• batch untrash:
  Move messages out of trash can

  message_client.batch_untrash(ids=["aaa","bbb"])

Message

Message is an ORM model. It offer several properties and methods same as gmail api doc.

properties: id, thread_id, label_ids, subject, date, from_, to, body, parts

methods: delete, trash, untrash

Frequently asked quentions

1. Why my refresh token expired after 7 days?

   In google's refresh token policy, if the app in google is a test app, the refresh token expired after 7 days. You need to publish your app to get a long-lived refresh token.

For Developers

Contributing

This is an immature project. PRs are welcome. Feel free to ask any questions or offer suggestions

Version Control

Currently this project use pip tools for version control. https://github.com/jazzband/pip-tools To update requirements.txt, run pip-compile requirements.in

momomail's Issues

Mentioned Functions don't exist

Some mentioned Functions within the readme.md doesn't exist, such as: search_message, get_message
i had to use message_client.list(search_string="twitter") instead of search_message

Error:

Traceback (most recent call last):
  File "/home/leonard/PROJECTS/POC-GEN-AI/gmail-momomail/main.py", line 8, in <module>
    messages=message_client.search_messages("twitter")
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
AttributeError: 'MessageClient' object has no attribute 'search_messages'

Suggestion:
Functions need to be created

Deleted package detected

I'm a Cyber Security researcher and developer of PackjGuard [1] to address open-source software supply chain attacks.

Issue

During my research, I detected a deleted package in this repository.

Details

Specifically, the package momomail mentioned in file README at line 7 does not exist on the public PyPI registry. A bad actor can hijack this package to propagate malicious code.

Impact

Not only your apps/services using https://github.com/YYLIZH/momomail repo code are vulnerable to this attack, but the users of your open-source Github repo could also fall victim.

You could read more about such attacks here: https://medium.com/@alex.birsan/dependency-confusion-4a5d60fec610

Remediation

Please highlight this in file README and register a placeholder package for momomail on public PyPI soon to remediate.

To automatically fix such issues in future, please install PackjGuard Github app [1].

Thanks!

1. PackjGuard is a Github app that monitors your repos 24x7, detects vulnerable/malicious/risky open-source dependencies, and creates pull requests for auto remediation: https://github.com/marketplace/packjguard