How to Automate Gmail Inbox Sorting using the API

1#!/usr/bin/env python3
2"""Gmail Inbox Sorter — creates labels, filters, and retroactively sorts existing mail."""
3import os
4import time
5import logging
6from googleapiclient.discovery import build
7from google.oauth2.credentials import Credentials
8from google_auth_oauthlib.flow import InstalledAppFlow
9from google.auth.transport.requests import Request
10
11logging.basicConfig(level=logging.INFO, format='%(asctime)s %(levelname)s %(message)s')
12log = logging.getLogger(__name__)
13
14SCOPES = [
15    'https://www.googleapis.com/auth/gmail.settings.basic',
16    'https://www.googleapis.com/auth/gmail.modify',
17    'https://www.googleapis.com/auth/gmail.labels'
18]
19
20SORTING_RULES = [
21    {
22        'label_name': 'Newsletters',
23        'label_color': {'textColor': '#ffffff', 'backgroundColor': '#16a765'},
24        'filter_criteria': {'query': 'list: OR unsubscribe'},
25        'sort_query': 'list: OR unsubscribe in:inbox'
26    },
27    {
28        'label_name': 'Notifications',
29        'label_color': {'textColor': '#ffffff', 'backgroundColor': '#4986e7'},
30        'filter_criteria': {'from': 'noreply@ OR no-reply@'},
31        'sort_query': 'from:(noreply OR no-reply) in:inbox'
32    },
33    {
34        'label_name': 'Receipts',
35        'label_color': {'textColor': '#000000', 'backgroundColor': '#f691b2'},
36        'filter_criteria': {'query': 'subject:(receipt OR order OR invoice)'},
37        'sort_query': 'subject:(receipt OR order OR invoice) in:inbox'
38    }
39]
40
41def get_credentials():
42    creds = None
43    if os.path.exists('token.json'):
44        creds = Credentials.from_authorized_user_file('token.json', SCOPES)
45    if not creds or not creds.valid:
46        if creds and creds.expired and creds.refresh_token:
47            creds.refresh(Request())
48        else:
49            flow = InstalledAppFlow.from_client_secrets_file('credentials.json', SCOPES)
50            creds = flow.run_local_server(port=0)
51        with open('token.json', 'w') as f:
52            f.write(creds.to_json())
53    return creds
54
55def get_or_create_label(service, name, color):
56    labels = service.users().labels().list(userId='me').execute().get('labels', [])
57    for label in labels:
58        if label['name'] == name:
59            log.info(f'Label exists: {name} ({label["id"]})')
60            return label['id']
61    result = service.users().labels().create(
62        userId='me', body={'name': name, 'messageListVisibility': 'show',
63                           'labelListVisibility': 'labelShow', 'color': color}
64    ).execute()
65    log.info(f'Created label: {name} ({result["id"]})')
66    return result['id']
67
68def sort_existing_mail(service, query, label_id):
69    ids, page_token = [], None
70    while True:
71        params = {'userId': 'me', 'q': query, 'maxResults': 500}
72        if page_token:
73            params['pageToken'] = page_token
74        res = service.users().messages().list(**params).execute()
75        ids.extend([m['id'] for m in res.get('messages', [])])
76        page_token = res.get('nextPageToken')
77        if not page_token:
78            break
79    for i in range(0, len(ids), 1000):
80        service.users().messages().batchModify(
81            userId='me',
82            body={'ids': ids[i:i+1000], 'addLabelIds': [label_id], 'removeLabelIds': ['INBOX']}
83        ).execute()
84        time.sleep(0.5)
85    return len(ids)
86
87def main():
88    service = build('gmail', 'v1', credentials=get_credentials())
89    for rule in SORTING_RULES:
90        label_id = get_or_create_label(service, rule['label_name'], rule['label_color'])
91        service.users().settings().filters().create(
92            userId='me',
93            body={'criteria': rule['filter_criteria'],
94                  'action': {'addLabelIds': [label_id], 'removeLabelIds': ['INBOX']}}
95        ).execute()
96        log.info(f'Filter created for {rule["label_name"]}')
97        count = sort_existing_mail(service, rule['sort_query'], label_id)
98        log.info(f'Sorted {count} existing messages into {rule["label_name"]}')
99
100if __name__ == '__main__':
101    main()