Get all messages with a specific tag

import os
import sys
import time
from datetime import datetime, timedelta, timezone

import requests

BASE_URL = "https://c1.emailgistics.com/api/v1"
API_KEY = os.environ["EMAILGISTICS_API_KEY"]
HEADERS = {"Authorization": f"Bearer {API_KEY}"}


def resolve_tag(tag_name: str, mailbox_email: str) -> tuple[str, str]:
    """One call resolves both report inputs: mailboxId and tagId."""
    response = requests.get(f"{BASE_URL}/admin/mailboxes", headers=HEADERS, timeout=30)
    response.raise_for_status()

    mailbox = next(
        (m for m in response.json()["mailboxes"]
         if m["mailboxEmail"].lower() == mailbox_email.lower()),
        None,
    )
    if mailbox is None:
        sys.exit(f"Mailbox {mailbox_email!r} not found (or not in this key's allowlist).")

    tag = next(
        (t for t in mailbox["tags"]
         if t["tagName"].lower() == tag_name.lower() and t["active"]),
        None,
    )
    if tag is None:
        names = ", ".join(t["tagName"] for t in mailbox["tags"] if t["active"])
        sys.exit(f"Tag {tag_name!r} not found in {mailbox_email}. Active tags: {names}")

    return mailbox["mailboxId"], tag["tagId"]


def messages_with_tag(
    tag_name: str,
    mailbox_email: str,
    activity_start: str,
    activity_end: str,
) -> list[dict]:
    mailbox_id, tag_id = resolve_tag(tag_name, mailbox_email)

    envelope = requests.post(
        f"{BASE_URL}/reports/receivedMessageDetail"
        "?fieldGroup=basic,tags&includeDetails=true&max=500",
        headers=HEADERS,
        json={
            "mailboxId": mailbox_id,
            "activityType": "received",
            "activityStart": activity_start,
            "activityEnd": activity_end,
            "tags": [tag_id],
        },
        timeout=30,
    ).json()

    messages, delay = [], 2
    while True:
        if envelope["status"] == "error":
            raise RuntimeError(envelope["error"])
        if envelope["status"] == "done":
            messages.extend(envelope["result"]["data"])
            next_link = envelope["_links"].get("next")
            if next_link is None:
                return messages
            url = next_link["href"]
        else:
            time.sleep(delay)
            delay = min(delay * 2, 30)
            url = envelope["_links"]["self"]["href"]
        envelope = requests.get(url, headers=HEADERS, timeout=30).json()


def iso(dt: datetime) -> str:
    """The API requires full ISO 8601 datetimes; a bare date is rejected with 400."""
    return dt.strftime("%Y-%m-%dT%H:%M:%SZ")


if __name__ == "__main__":
    if len(sys.argv) not in (3, 5):
        sys.exit(f"Usage: {sys.argv[0]} <tag-name> <mailbox-email> [<start> <end>]")

    now = datetime.now(timezone.utc)
    start = sys.argv[3] if len(sys.argv) == 5 else iso(now - timedelta(days=30))
    end = sys.argv[4] if len(sys.argv) == 5 else iso(now)

    rows = messages_with_tag(sys.argv[1], sys.argv[2], start, end)
    print(f"{len(rows)} message(s) tagged {sys.argv[1]!r}:")
    for m in rows:
        tags = ", ".join(t.get("tagName", t["tagId"]) for t in m.get("tags", []))
        print(f"  [{m['status']:>7}] {m['receivedTimestamp']}  {m['fromEmail']}  {m['subject']}")
        print(f"           tags: {tags}")