Gmail-regels beheren via de API

Gmail-filters via de API

Gmail-filters zijn automatische regels die acties uitvoeren op inkomende e-mails. Via de Gmail API kun je filters programmatisch beheren. Dat is handig voor het uitrollen van standaardfilters naar meerdere gebruikers, het importeren van filters uit een configuratiesysteem of het automatisch aanpassen van filters op basis van bedrijfslogica.

Authenticatie

from google.oauth2.credentials import Credentials
from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build
import os

SCOPES = [
    'https://www.googleapis.com/auth/gmail.settings.basic',
    'https://www.googleapis.com/auth/gmail.labels',
]

def get_gmail_service():
    creds = None
    if os.path.exists('token.json'):
        creds = Credentials.from_authorized_user_file('token.json', SCOPES)

    if not creds or not creds.valid:
        flow = InstalledAppFlow.from_client_secrets_file('credentials.json', SCOPES)
        creds = flow.run_local_server(port=0)
        with open('token.json', 'w') as token:
            token.write(creds.to_json())

    return build('gmail', 'v1', credentials=creds)

Bestaande filters ophalen

def haal_filters_op(service):
    result = service.users().settings().filters().list(userId='me').execute()
    filters = result.get('filter', [])

    for f in filters:
        criteria = f.get('criteria', {})
        action = f.get('action', {})
        print(f'Filter ID: {f["id"]}')
        print(f'  Van: {criteria.get("from", "Niet ingesteld")}')
        print(f'  Onderwerp bevat: {criteria.get("subject", "Niet ingesteld")}')
        print(f'  Acties: {action}')
        print('---')

    return filters

Een filter aanmaken

Een filter bestaat uit twee delen: criteria (waar het filter op matcht) en action (wat er moet gebeuren). Acties verwijzen naar label-id's, niet naar labelnamen, dus zoek de id eerst op of maak het label aan.

def maak_filter_aan(service, van=None, onderwerp=None, label_naam=None,
                     archiveren=False, markeer_gelezen=False, verwijderen=False):
    criteria = {}
    if van:
        criteria['from'] = van
    if onderwerp:
        criteria['subject'] = onderwerp

    add_labels = []
    remove_labels = []

    if label_naam:
        label_id = haal_of_maak_label(service, label_naam)
        add_labels.append(label_id)

    if archiveren:
        remove_labels.append('INBOX')

    if markeer_gelezen:
        remove_labels.append('UNREAD')

    if verwijderen:
        add_labels.append('TRASH')

    filter_body = {
        'criteria': criteria,
        'action': {
            'addLabelIds': add_labels,
            'removeLabelIds': remove_labels
        }
    }

    result = service.users().settings().filters().create(
        userId='me',
        body=filter_body
    ).execute()

    print(f'Filter aangemaakt: {result["id"]}')
    return result['id']

def haal_of_maak_label(service, naam):
    labels = service.users().labels().list(userId='me').execute()
    for label in labels.get('labels', []):
        if label['name'] == naam:
            return label['id']

    nieuw_label = service.users().labels().create(
        userId='me',
        body={'name': naam, 'labelListVisibility': 'labelShow', 'messageListVisibility': 'show'}
    ).execute()

    return nieuw_label['id']

Filters in bulk aanmaken

Voor het uitrollen van een vaste set filters is het handig om de configuratie los van de code te houden, bijvoorbeeld in een JSON- of YAML-bestand. Zo kunnen niet-ontwikkelaars de filters aanpassen zonder de code te raken.

def importeer_filters_vanuit_config(service, filter_configuraties):
    resultaten = []

    for config in filter_configuraties:
        filter_id = maak_filter_aan(
            service,
            van=config.get('van'),
            onderwerp=config.get('onderwerp'),
            label_naam=config.get('label'),
            archiveren=config.get('archiveren', False),
            markeer_gelezen=config.get('markeer_gelezen', False)
        )
        resultaten.append({'config': config, 'filter_id': filter_id})

    return resultaten

filter_configuraties = [
    {
        'van': '@klantdomeinnaam.nl',
        'label': 'Klant A',
        'markeer_gelezen': False
    },
    {
        'onderwerp': '[SPAM]',
        'archiveren': True,
        'markeer_gelezen': True
    },
    {
        'van': 'noreply@github.com',
        'label': 'GitHub',
        'archiveren': True
    }
]

service = get_gmail_service()
resultaten = importeer_filters_vanuit_config(service, filter_configuraties)

Filter verwijderen

def verwijder_filter(service, filter_id):
    service.users().settings().filters().delete(
        userId='me',
        id=filter_id
    ).execute()
    print(f'Filter verwijderd: {filter_id}')

def verwijder_alle_filters(service):
    filters = haal_filters_op(service)
    for f in filters:
        verwijder_filter(service, f['id'])
    print(f'{len(filters)} filters verwijderd.')

Uitrollen naar een heel team

Wil je filters niet voor je eigen account maar voor alle gebruikers in je Google Workspace-organisatie beheren, dan werk je met een serviceaccount en Domain-Wide Delegation. Het serviceaccount handelt dan namens elke gebruiker (impersonatie), zonder dat die gebruiker zelf hoeft in te loggen.

Veelgestelde vragen