---
name: email-import
description: Help a Letters Home user export mail, choose original messages or both sides of correspondence, and upload the selected archive to an owned collection.
---

# Saved email import

Use `get_export_workflow` first. For Gmail, guide one Takeout Mail export from the mailbox holding the messages. No Gmail OAuth or label step is required. Ask for the **email address** and make the user choose `originals_only` or `both_directions` before filtering. Explain the choices in plain language: original messages only selects messages sent from that address that do not look like replies; both directions selects messages to or from that address, including replies. Neither mode automatically includes unrelated third-party messages merely because Gmail groups them in a conversation.

When the user identifies a downloaded Takeout ZIP and the local host has file tools, extract only raw `.mbox` files under `Takeout/Mail` into the approved import folder. Check ZIP entries locally; reject path traversal, symlinks, and unreasonable expanded size. Do not display mail text or private filenames in chat. Never upload an untouched Takeout ZIP or an unfiltered All Mail MBOX.

Use `start_address_filter` with the explicit selection on the raw MBOX inside `LETTERS_HOME_IMPORT_DIR`, then poll `get_address_filter_status` until `COMPLETE`, `EMPTY`, `FAILED`, or `CANCELLED`. A portable host may provide `${PLUGIN_DATA}` as this folder; Claude Code prompts for the folder when the plugin starts. If the folder is missing, have the user or host choose an absolute folder before server startup. The filter writes only selected messages to a neutral-name MBOX in that folder and never changes the source. Report total, matched, reply-excluded, uncertain-reply, and unparseable counts. Original-only uses `In-Reply-To` and `References`, plus a conservative reply-subject hint; replies missing those signals can still pass. Do not claim exact completeness or perfect reply detection. On `EMPTY`, do not upload. On failure or cancellation, do not use partial output. For multiple Takeout ZIP parts, filter each raw MBOX separately and upload one completed selected output at a time.

Call `inspect_archive` on the completed filtered MBOX. Treat its result as a metadata/signature check, not message-content approval. Use `get_collection_upload_link` with the UUID from the user-provided Letters Home project URL. Have the user verify collection name and supported mode (`EMAIL_UPLOAD_IMPORT` or `EMAIL_COLLECTION`) and sign in through the normal browser flow. When the local host has browser and file controls, operate the signed-in Settings uploader: select the **filtered** output, start upload after the specific file and collection are authorized, and monitor to terminal success or failure. Keep browser credentials in the browser; never extract cookies or call private APIs with borrowed session material. Report imported/skipped counts and help review sample letters. If browser controls are unavailable, provide the direct link and exact file-selection steps.

The host/model sees the sender address and source path in tool arguments, and the output path in status. Recommend a narrow local folder and neutral filenames. Do not quote message contents, subjects, unrelated addresses, Google download URLs, tokens, or cookies. Keep the original export until import review, then help the user remove extra local copies according to their retention choice. The filtered output persists until deleted; a process crash can leave a hidden partial file.

Other providers may export raw MBOX or EML. The address filter accepts raw MBOX only. `.eml`, raw `.mbox`, and ZIPs of supported saved-email files can use the existing uploader; Outlook `.pst` and `.olm` are not accepted. Do not ask for Gmail passwords, app passwords, or OAuth consent.