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 example@domain.com:
+ ```
+ python send_emails.py example@domain.com "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 example@domain.com as **Unread**:
+ ```
+ python mark_emails.py "example@domain.com" -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 = 'our_email@gmail.com'
+
+
+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