DEV Community

Steven Keil
Steven Keil

Posted on AI-assisted

Finding Email Attachments Yourself with IMAP Search (and When You'd Rather Not)

#python #email #automation #tutorial

If you only need last month's receipts, you don't need a tool. Gmail's search operators and a few lines of Python will get you there.

Start with Gmail search syntax

In the Gmail search bar:

has:attachment filename:pdf after:2026/09/01 before:2026/10/01
Enter fullscreen mode Exit fullscreen mode

Combine from:, subject: and has:attachment to narrow things down, e.g. from:billing@example.com has:attachment.

Pull attachments via IMAP

If you want them saved locally without clicking through each email, Gmail supports IMAP with an app password (this requires 2-step verification to be enabled first). Note that some company (Workspace) accounts block app passwords through an admin policy. A minimal script:

import imaplib, email, os

mail = imaplib.IMAP4_SSL("imap.gmail.com")
mail.login("you@gmail.com", "your-app-password")
mail.select("inbox")

# Gmail search extension via IMAP
status, data = mail.search(None, 'X-GM-RAW "has:attachment after:2026/09/01"')

for num in data[0].split():
    status, msg_data = mail.fetch(num, "(RFC822)")
    msg = email.message_from_bytes(msg_data[0][1])
    for part in msg.walk():
        if part.get_content_disposition() == "attachment":
            filename = part.get_filename()
            if filename:
                safe_name = os.path.basename(filename)  # never trust a path from an email
                with open(safe_name, "wb") as f:
                    f.write(part.get_payload(decode=True))
                print("Saved:", safe_name)

mail.logout()
Enter fullscreen mode Exit fullscreen mode

This works for Gmail and any other IMAP mailbox (Outlook, Yahoo, iCloud, GMX, web.de) if you swap the host and use that provider's IMAP settings.

A few gotchas before you rely on this for anything recurring

  • Re-running the script will save the same file twice unless you add your own dedupe logic.
  • Tiny inline images (signature logos) show up as "attachments" too and will clutter your folder.
  • Two attachments with the same name overwrite each other.
  • If you want things sorted into dated folders automatically, or want to keep it running in the background so new invoices get saved the moment they arrive, you'll need to build that layer yourself.

If you'd rather skip writing and maintaining that part

I made a small tool that does exactly this. It filters by sender, subject, Gmail search, date and file type, skips signature images and tiny files, never saves the same file twice, sorts everything into dated folders like 2026/10/2026-10-01_Invoice 42.pdf, and has a watch mode so it keeps running. It works with Gmail (app password and 2-step verification) and any IMAP mailbox, and is read-only by default.

It is mine and it is paid, 12 EUR: https://skeilster.gumroad.com/l/gmail-attachment-saver

Top comments (0)