Gmail_Archive

Gmail Archive — by John Halfords

For download, go to the Github page…

A Windows PowerShell 5.1 utility for creating an independent, browsable HTML archive of Gmail conversations, including attachments. An optional separate cleanup script can move fully verified messages to Gmail Trash.

Features

  1. Archive entire conversations: When at least one message in a conversation carries the configured trigger label (for example ToArchive), archive every message in that conversation.
  2. Include all conversation messages: Include messages already in Gmail Trash when the conversation also has an eligible trigger-labeled message outside Trash.
  3. Evaluate labels across the conversation: Collect labels from all messages, not just the last message.
  4. Support multiple archive folders: If a conversation has multiple relevant user labels, make the complete archive available in each corresponding folder.
  5. Preserve conversation content: Keep messages in chronological order, with attachments and locally saved images where available.
  6. Use real email participants: Derive correspondent names from actual From/To/Cc headers, exclude configured own addresses, and separate multiple names with , .
  7. Avoid unnecessary rewrites: Use the archive index to recognize existing content and extend archives when new messages appear.
  8. Preserve original identifiers: Track Gmail message IDs and thread IDs in the index, including when conversations are merged into one archive.
  9. Keep the archive independently usable: Save browsable HTML and assets on disk, so archived conversations can be viewed without Gmail.

Requirements

Files and layout

Gmail_Archive/
├── private/
│   ├── GmailOAuth.json
│   └── GmailToken.json
├── .gitignore
├── Gmail_Archive_Delete_v1.03.ps1
├── Gmail_Archive_OAuth_v1.00.ps1
├── Gmail_Archive_Settings.example.psd1
├── Gmail_Archive_Settings.psd1
├── Gmail_Archive_v1.00.ps1
├── README.md
├── Start_Gmail_Archive.cmd
├── Start_Gmail_Archive_Delete.cmd
└── Start_Gmail_OAuth.cmd

The archive destination (configured by ArchiveRoot) contains the HTML archives, assets, an ArchiefIndex.json, and the HTML log. It does not need to be the same folder as the scripts.

Configuration

Copy Gmail_Archive_Settings.example.psd1 to Gmail_Archive_Settings.psd1. Edit the copy for your paths, labels and Gmail addresses. Every setting is documented with an English comment in the example file.

Important settings:

Setting Purpose
ScriptFolder Folder containing scripts, settings and private/
ArchiveRoot Destination folder for the archive and index
TriggerLabel Gmail label that selects conversations for archiving
OwnAddresses Your email addresses, excluded from participant names
MaxSubjectLength Configurable filename subject limit (default 35)
MaxThreads Maximum conversations to check in a single run
DryRun Preview archive processing
UpdateExisting Allow extending existing archived conversations
SaveAttachments, DownloadImages Control offline asset preservation
ApiRequestIntervalMs, ApiMinIntervalMs API pacing controls
ApiRetryCount, ApiRetrySeconds API retry settings
LogFile, MaxLogSizeMB HTML log location and retention size

OAuth setup

For beginners: Google’s Gmail API setup guide (follow the Google Cloud and OAuth setup steps; Python installation is not required).

  1. Create a Google Cloud project, enable the Gmail API, and create OAuth credentials for a desktop application.
  2. Create a private/ folder next to the scripts and save the downloaded OAuth credentials as GmailOAuth.json (or the filename specified in settings).
  3. Run Start_Gmail_OAuth.cmd to authorize Gmail access.
  4. The OAuth helper saves the authorization token as private/GmailToken.json (or the filename specified in settings).
  5. Keep both JSON files secret; never share them.

Gmail Archive requires the gmail.readonly scope, while Gmail Archive Delete requires gmail.modify. The OAuth helper requests both scopes.

Access tokens are refreshed during long runs. The scripts read the OAuth files from private/.

Optional: move verified messages to Gmail Trash

The Delete script is intentionally separate. It checks the current Gmail message IDs against the archive index per conversation. If there is any discrepancy, the entire conversation is blocked. For eligible conversations, it uses individual messages.trash operations, not threads.trash, and requires confirmation before making Gmail changes. It never deletes local archive files. Trash is not permanent deletion, but emptying Gmail Trash later is permanent; verify your archive first.

Run

Simply double-click the appropriate .cmd file:

The .cmd files are the recommended way to run Gmail Archive on Windows. They automatically start the corresponding PowerShell scripts from the correct directory. PowerShell’s execution policy is temporarily bypassed only for the launched PowerShell process. Your system’s execution policy remains unchanged.

Start with DryRun = $true when validating paths and label selection. Inspect the generated archive and ArchiefIndex.json after a real run before considering deletion.

Archiving never moves, deletes, or changes Gmail messages. It writes files to the configured archive destination.

Operational notes

Disclaimer

This software is provided “as is”, without warranty of any kind. Use it at your own risk. I am not responsible for any data loss, damage, or other consequences resulting from its use. Always - Always - Always verify your archives and keep backups before deleting Gmail messages.