apache/airflow

IMAP hook silently overwrites attachments with identical filenames

Open

#65870 opened on Apr 26, 2026

View on GitHub
 (1 comment) (0 reactions) (0 assignees)Python (44,809 stars) (16,781 forks)batch import
area:providersgood first issuekind:bugprovider:imap

Description

Under which category would you file this issue?

Providers

Apache Airflow version

3.2.1

What happened and how to reproduce it?

Problem

When using imap_hook.download_mail_attachments, attachments with identical filenames are saved to disk using the same name, which leads to silent overwriting of previously downloaded files.

This results in data loss without any warning, and there is currently no option to control this behavior.

How to reproduce

  1. Receive multiple emails with attachments sharing the same filename (e.g. report.xlsx)
  2. Call imap_hook.download_mail_attachments
  3. Inspect the output directory
  4. Observe that only one file is present, as earlier files were overwritten

What you think should happen instead?

There should be a configurable way to control how filename collisions are handled when saving attachments, for example:

  • either allow overwriting existing files
  • or preserve all files by automatically renaming them.

The current behavior should not be hardcoded without user control.

Possible improvement

Introduce a configurable parameter (e.g. overwrite_file or similar) that controls collision handling behavior:

  • overwrite_file=True → overwrite existing files (current behavior)
  • overwrite_file=False → preserve all files

This would make the behavior explicit and safe for different use cases.

Operating System

No response

Deployment

Official Apache Airflow Helm Chart

Apache Airflow Provider(s)

imap

Versions of Apache Airflow Providers

apache-airflow-providers-imap==3.11.0

Official Helm Chart version

Not Applicable

Kubernetes Version

No response

Helm Chart configuration

No response

Docker Image customizations

No response

Anything else?

A previous implementation attempt and discussion can be found here:

https://github.com/apache/airflow/pull/62321

Are you willing to submit PR?

  • Yes I am willing to submit a PR!

Code of Conduct

Contributor guide

Tech stack
python
Domain
backend
Issue type
feature
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
3
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-3 hours
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
fresh
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
clear
Prerequisites
PythonApache Airflow basicsFile I/O
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
60
Research direction
The issue requests a configurable parameter for handling filename collisions when saving attachments from IMAP. A previous attempt is referenced in PR #62321, which can be reviewed for implementation insights. The main file to modify is likely `airflow/providers/imap/hooks/imap.py`, specifically the `download mail attachments` method. Consider adding an `overwrite` keyword argument (default True to preserve current behavior) and using a renaming strategy (e.g., appending a counter) when `overwrite=False`. The maintainer's feedback on the PR should be consulted to align with project standards.