Example

Custom script — bulk tag by sender domain

Every Tidy integration starts with a script. This example shows the shape: authenticate with a PAT, page through results, and mutate in place.

The script below scans every email in the workspace from a given domain and applies a vendor label to each one.

Prerequisites

1. A personal access token from Settings → Security → Personal Access Tokens.
2. pip install tidy-sdk or npm install @tidy/sdk.

Script

"""Bulk-tag every email from a given domain with a 'vendor' label.

Run: TIDY_PAT=... python bulk_tag_vendor.py acme.com
"""
import os, sys
from tidy_sdk import Tidy

client = Tidy(token=os.environ["TIDY_PAT"])
domain = sys.argv[1]

cursor = None
tagged = 0
while True:
    page = client.emails.list(
        query=f"from:*@{domain}",
        limit=100,
        cursor=cursor,
    )
    for email in page.emails:
        client.emails.patch(email.id, labels_add=["vendor"])
        tagged += 1
    if not page.next_cursor:
        break
    cursor = page.next_cursor

print(f"Tagged {tagged} emails from {domain}")

Run it

export TIDY_PAT=tidy_pat_xxx
python bulk_tag_vendor.py acme.com

What it illustrates

• Pagination via next_cursor — Tidy never returns unbounded lists.
• Idempotent mutation: re-running the script is safe because labels_add is a set-union.
• Rate limiting: the SDK retries 429s automatically with jitter. No extra code needed.

Where to go from here

• Swap the patch call for a client.tasks.create to turn "everything from this domain" into actionable work.
• Subscribe to email.created via webhooks to tag new mail in real time instead of periodically.
• See the full endpoint list in the API reference.

Base URL used: https://qa.tidy.engineering.