add gmail api tutorial

Author: x4nth055

README.md

@@ -130,6 +130,7 @@ This is a repository of all the tutorials of [The Python Code](https://www.thepy
     - [How to Make a URL Shortener in Python](https://www.thepythoncode.com/article/make-url-shortener-in-python). ([code](general/url-shortener))
     - [How to Get Google Page Ranking in Python](https://www.thepythoncode.com/article/get-google-page-ranking-by-keyword-in-python). ([code](general/getting-google-page-ranking))
     - [How to Make a Telegram Bot in Python](https://www.thepythoncode.com/article/make-a-telegram-bot-in-python). ([code](general/telegram-bot))
+    - [How to Use Gmail API in Python](https://www.thepythoncode.com/article/use-gmail-api-in-python). ([code](general/gmail-api))
 
 - ### [Database](https://www.thepythoncode.com/topic/using-databases-in-python)
     - [How to Use MySQL Database in Python](https://www.thepythoncode.com/article/using-mysql-database-in-python). ([code](database/mysql-connector))

general/gmail-api/README.md

@@ -0,0 +1,66 @@
+# [How to Use Gmail API in Python](https://www.thepythoncode.com/article/use-gmail-api-in-python)
+To use the scripts here:
+- Create your credentials file in Google API dashboard and putting it in the current directory, follow [this tutorial](https://www.thepythoncode.com/article/use-gmail-api-in-python) for detailed information.
+- `pip3 install -r requirements.txt`
+- Change `our_email` variable in `common.py` to your gmail address.
+- To send emails, use the `send_emails.py` script:
+    ```
+    python send_emails.py --help
+    ```
+    **Output:**
+    ```
+    usage: send_emails.py [-h] [-f FILES [FILES ...]] destination subject body
+
+    Email Sender using Gmail API
+
+    positional arguments:
+    destination           The destination email address
+    subject               The subject of the email
+    body                  The body of the email
+
+    optional arguments:
+    -h, --help            show this help message and exit
+    -f FILES [FILES ...], --files FILES [FILES ...]
+                            email attachments
+    ```
+    For example, sending to [email protected]:
+    ```
+    python send_emails.py [email protected] "This is a subject" "Body of the email" --files file1.pdf file2.txt file3.img
+    ```
+- To read emails, use the `read_emails.py` script. Downloading & parsing emails for Python related emails:
+    ```
+    python read_emails.py "python"
+    ```
+    This will output basic information on all matched emails and creates a folder for each email along with attachments and HTML version of the emails.
+- To mark emails as **read** or **unread**, consider using `mark_emails.py`:
+    ```
+    python mark_emails.py --help
+    ```
+    **Output**:
+    ```
+    usage: mark_emails.py [-h] [-r] [-u] query
+
+    Marks a set of emails as read or unread
+
+    positional arguments:
+    query         a search query that selects emails to mark
+
+    optional arguments:
+    -h, --help    show this help message and exit
+    -r, --read    Whether to mark the message as read
+    -u, --unread  Whether to mark the message as unread
+    ```
+    Marking emails from **Google Alerts** as **Read**:
+    ```
+    python mark_emails.py "Google Alerts" --read
+    ```
+    Marking emails sent from [email protected] as **Unread**:
+    ```
+    python mark_emails.py "[email protected]" -u
+    ```
+- To delete emails, consider using `delete_emails.py` script, e.g: for deleting emails about Bitcoin:
+    ```
+    python delete_emails.py "bitcoin"
+    ```
+- If you want the full code, consider using `tutorial.ipynb` file.
+- Or if you want a all-in-one script, `gmail_api.py` is here as well!

general/gmail-api/common.py

@@ -0,0 +1,43 @@
+import os
+import pickle
+# Gmail API utils
+from googleapiclient.discovery import build
+from google_auth_oauthlib.flow import InstalledAppFlow
+from google.auth.transport.requests import Request
+
+# Request all access (permission to read/send/receive emails, manage the inbox, and more)
+SCOPES = ['https://mail.google.com/']
+our_email = '[email protected]'
+
+
+def gmail_authenticate():
+    creds = None
+    # the file token.pickle stores the user's access and refresh tokens, and is
+    # created automatically when the authorization flow completes for the first time
+    if os.path.exists("token.pickle"):
+        with open("token.pickle", "rb") as token:
+            creds = pickle.load(token)
+    # if there are no (valid) credentials availablle, let the user log in.
+    if not creds or not creds.valid:
+        if creds and creds.expired and creds.refresh_token:
+            creds.refresh(Request())
+        else:
+            flow = InstalledAppFlow.from_client_secrets_file('credentials.json', SCOPES)
+            creds = flow.run_local_server(port=0)
+        # save the credentials for the next run
+        with open("token.pickle", "wb") as token:
+            pickle.dump(creds, token)
+    return build('gmail', 'v1', credentials=creds)
+
+
+def search_messages(service, query):
+    result = service.users().messages().list(userId='me',q=query).execute()
+    messages = [ ]
+    if 'messages' in result:
+        messages.extend(result['messages'])
+    while 'nextPageToken' in result:
+        page_token = result['nextPageToken']
+        result = service.users().messages().list(userId='me',q=query, pageToken=page_token).execute()
+        if 'messages' in result:
+            messages.extend(result['messages'])
+    return messages

general/gmail-api/delete_emails.py

@@ -0,0 +1,18 @@
+from common import gmail_authenticate, search_messages
+
+def delete_messages(service, query):
+    messages_to_delete = search_messages(service, query)
+    # it's possible to delete a single message with the delete API, like this:
+    # service.users().messages().delete(userId='me', id=msg['id'])
+    # but it's also possible to delete all the selected messages with one query, batchDelete
+    return service.users().messages().batchDelete(
+      userId='me',
+      body={
+          'ids': [ msg['id'] for msg in messages_to_delete]
+      }
+    ).execute()
+
+if __name__ == "__main__":
+    import sys
+    service = gmail_authenticate()
+    delete_messages(service, sys.argv[1])

general/gmail-api/gmail_api.py

@@ -0,0 +1,45 @@
+# for parsing commandline arguments
+import argparse
+from common import search_messages, gmail_authenticate
+from read_emails  import read_message
+from send_emails  import send_message
+from delete_emails import delete_messages
+from mark_emails  import mark_as_read, mark_as_unread
+
+
+if __name__ == '__main__':
+    parser = argparse.ArgumentParser(description="Send/Search/Delete/Mark messages using gmail's API.")
+    subparsers = parser.add_subparsers(help='Subcommands')
+    parser_1 = subparsers.add_parser('send', help='Send an email')
+    parser_1.add_argument('destination', type=str, help='The destination email address')
+    parser_1.add_argument('subject', type=str, help='The subject of the email')
+    parser_1.add_argument('body', type=str, help='The body of the email')
+    parser_1.add_argument('files', type=str, help='email attachments', nargs='+')
+    parser_1.set_defaults(action='send')
+    parser_2 = subparsers.add_parser('delete', help='Delete a set of emails')
+    parser_2.add_argument('query', type=str, help='a search query that selects emails to delete')
+    parser_2.set_defaults(action='delete')
+    parser_3 = subparsers.add_parser('mark', help='Marks a set of emails as read or unread')
+    parser_3.add_argument('query', type=str, help='a search query that selects emails to mark')
+    parser_3.add_argument('read_status', type=bool, help='Whether to mark the message as unread, or as read')
+    parser_3.set_defaults(action='mark')
+    parser_4 = subparsers.add_parser('search', help='Marks a set of emails as read or unread')
+    parser_4.add_argument('query', type=str, help='a search query, which messages to display')
+    parser_4.set_defaults(action='search')
+    args = parser.parse_args()
+    service = gmail_authenticate()
+    if args.action == 'send':
+        # TODO: add attachements
+        send_message(service, args.destination, args.subject, args.body, args.files)
+    elif args.action == 'delete':
+        delete_messages(service, args.query)
+    elif args.action == 'mark':
+        print(args.unread_status)
+        if args.read_status:
+            mark_as_read(service, args.query)
+        else:
+            mark_as_unread(service, args.query)
+    elif args.action == 'search':
+        results = search_messages(service, args.query)
+        for msg in results:
+            read_message(service, msg)

general/gmail-api/mark_emails.py

@@ -0,0 +1,35 @@
+from common import gmail_authenticate, search_messages
+
+def mark_as_read(service, query):
+    messages_to_mark = search_messages(service, query)
+    return service.users().messages().batchModify(
+      userId='me',
+      body={
+          'ids': [ msg['id'] for msg in messages_to_mark ],
+          'removeLabelIds': ['UNREAD']
+      }
+    ).execute()
+
+def mark_as_unread(service, query):
+    messages_to_mark = search_messages(service, query)
+    return service.users().messages().batchModify(
+        userId='me',
+        body={
+            'ids': [ msg['id'] for msg in messages_to_mark ],
+            'addLabelIds': ['UNREAD']
+        }
+    ).execute()
+
+if __name__ == "__main__":
+    import argparse
+    parser = argparse.ArgumentParser(description="Marks a set of emails as read or unread")
+    parser.add_argument('query', help='a search query that selects emails to mark')
+    parser.add_argument("-r", "--read", action="store_true", help='Whether to mark the message as read')
+    parser.add_argument("-u", "--unread", action="store_true", help='Whether to mark the message as unread')
+
+    args = parser.parse_args()
+    service = gmail_authenticate()
+    if args.read:
+        mark_as_read(service, args.query)
+    elif args.unread:
+        mark_as_unread(service, args.query)

general/gmail-api/read_emails.py

@@ -0,0 +1,132 @@
+import os
+import sys
+# for encoding/decoding messages in base64
+from base64 import urlsafe_b64decode
+from common import gmail_authenticate, search_messages
+
+
+def get_size_format(b, factor=1024, suffix="B"):
+    """
+    Scale bytes to its proper byte format
+    e.g:
+        1253656 => '1.20MB'
+        1253656678 => '1.17GB'
+    """
+    for unit in ["", "K", "M", "G", "T", "P", "E", "Z"]:
+        if b < factor:
+            return f"{b:.2f}{unit}{suffix}"
+        b /= factor
+    return f"{b:.2f}Y{suffix}"
+
+
+def clean(text):
+    # clean text for creating a folder
+    return "".join(c if c.isalnum() else "_" for c in text)
+
+
+def parse_parts(service, parts, folder_name):
+    """
+    Utility function that parses the content of an email partition
+    """
+    if parts:
+        for part in parts:
+            filename = part.get("filename")
+            mimeType = part.get("mimeType")
+            body = part.get("body")
+            data = body.get("data")
+            file_size = body.get("size")
+            part_headers = part.get("headers")
+            if part.get("parts"):
+                # recursively call this function when we see that a part
+                # has parts inside
+                parse_parts(service, part.get("parts"), folder_name)
+            if mimeType == "text/plain":
+                # if the email part is text plain
+                if data:
+                    text = urlsafe_b64decode(data).decode()
+                    print(text)
+            elif mimeType == "text/html":
+                # if the email part is an HTML content
+                # save the HTML file and optionally open it in the browser
+                if not filename:
+                    filename = "index.html"
+                filepath = os.path.join(folder_name, filename)
+                print("Saving HTML to", filepath)
+                with open(filepath, "wb") as f:
+                    f.write(urlsafe_b64decode(data))
+            else:
+                # attachment other than a plain text or HTML
+                for part_header in part_headers:
+                    part_header_name = part_header.get("name")
+                    part_header_value = part_header.get("value")
+                    if part_header_name == "Content-Disposition":
+                        if "attachment" in part_header_value:
+                            # we get the attachment ID 
+                            # and make another request to get the attachment itself
+                            print("Saving the file:", filename, "size:", get_size_format(file_size))
+                            attachment_id = body.get("attachmentId")
+                            attachment = service.users().messages() \
+                                        .attachments().get(id=attachment_id, userId='me', messageId=msg['id']).execute()
+                            data = attachment.get("data")
+                            filepath = os.path.join(folder_name, filename)
+                            if data:
+                                with open(filepath, "wb") as f:
+                                    f.write(urlsafe_b64decode(data))                      
+
+
+def read_message(service, message_id):
+    """
+    This function takes Gmail API `service` and the given `message_id` and does the following:
+        - Downloads the content of the email
+        - Prints email basic information (To, From, Subject & Date) and plain/text parts
+        - Creates a folder for each email based on the subject
+        - Downloads text/html content (if available) and saves it under the folder created as index.html
+        - Downloads any file that is attached to the email and saves it in the folder created
+    """
+    msg = service.users().messages().get(userId='me', id=message_id['id'], format='full').execute()
+    # parts can be the message body, or attachments
+    payload = msg['payload']
+    headers = payload.get("headers")
+    parts = payload.get("parts")
+    folder_name = "email"
+    if headers:
+        # this section prints email basic info & creates a folder for the email
+        for header in headers:
+            name = header.get("name")
+            value = header.get("value")
+            if name == 'From':
+                # we print the From address
+                print("From:", value)
+            if name == "To":
+                # we print the To address
+                print("To:", value)
+            if name == "Subject":
+                # make a directory with the name of the subject
+                folder_name = clean(value)
+                # we will also handle emails with the same subject name
+                folder_counter = 0
+                while os.path.isdir(folder_name):
+                    folder_counter += 1
+                    # we have the same folder name, add a number next to it
+                    if folder_name[-1].isdigit() and folder_name[-2] == "_":
+                        folder_name = f"{folder_name[:-2]}_{folder_counter}"
+                    elif folder_name[-2:].isdigit() and folder_name[-3] == "_":
+                        folder_name = f"{folder_name[:-3]}_{folder_counter}"
+                    else:
+                        folder_name = f"{folder_name}_{folder_counter}"
+                os.mkdir(folder_name)
+                print("Subject:", value)
+            if name == "Date":
+                # we print the date when the message was sent
+                print("Date:", value)
+        
+    parse_parts(service, parts, folder_name)
+    print("="*50)
+
+if __name__ == "__main__":
+    service = gmail_authenticate()
+    # get emails that match the query you specify from the command lines
+    results = search_messages(service, sys.argv[1])
+    # for each email matched, read it (output plain/text to console & save HTML and attachments)
+    for msg in results:
+        read_message(service, msg)

general/gmail-api/requirements.txt

@@ -0,0 +1,3 @@
+google-api-python-client 
+google-auth-httplib2 
+google-auth-oauthlib