A mailbox automation can match the wrong messages or act on more of a conversation than expected. Pause its state-changing actions before investigating. A successful API response only establishes that an operation ran, not that its selection was correct.
Inspect selection before modification
Run a read-only or dry-run version that records message identifiers, counts, and the intended action. Review a small sample in the correct account. Check date boundaries, label conditions, sender aliases, and whether the query targets messages or whole threads.
Several GmailApp operations act on threads. Matching one message does not automatically justify changing every other message in the same conversation. Confirm the method’s actual scope before applying it to an active thread.
Separate labeling, archiving, Trash, and permanent deletion
Those operations have different effects and recovery options. Removing an inbox label is not the same as deleting a message. Moving something to Trash is different from immediately bypassing Trash and permanently deleting it.
Use only the permission needed for the approved task. Google’s scope guide distinguishes ordinary modification from immediate permanent deletion. Do not request the broadest scope to make an overbroad cleanup easier.
Apply a bounded change and verify it
Use a clearly identified test set and preserve its pre-change labels or relevant state where appropriate. Apply one intended action, read the result back, and inspect the messages. Stop if counts or affected records differ from the preview.
For an existing mistake, identify exactly which records the automation changed before attempting recovery. Do not empty Trash, delete diagnostic evidence, or run a second broad script to guess at the reversal. Follow the documented recovery route and your organization’s retention requirements, then correct the selection logic before resuming.
Browse Gmail & Google Account help
References
- Choose Gmail API scopes | Google for Developers
- Class GmailApp | Apps Script | Google for Developers
- Delete messages in Gmail
Reviewed against the linked official product guidance on November 3, 2026. Features, limits, screen labels, and access can vary by account, platform, region, and organization policy.