[29.0] Multiple runs of email retrieval on the same emails don't persist again

[Joshua (mynjj)]

Backport of #11612.

Fix at the email module layer of the bug causing additional entries to be persisted when retrieving the same email.

If the email had already been retrieved and stored, then such email is returned without further persisting, unless the previous email was stored without attachments, in which case only the attachment is added to such email message.

Tested the behavior against my email inbox locally.

Fix overview

• The outlook connector first checks if the email had been retrieved before, if so attachments are stored only if requested and they weren't there before.
• For the outlook connector to make the check if they had been retrieved before, it uses a new centralized FindRetrievedEmail on the email module, with the idea of centralizing this potentially tricky logic and benefitting other connectors.
• For adding attachments when the email has already been retrieved, a new overload of AddAttachment was needed, since the Modify on the email message that was run after, triggers a subscriber that errors when modifying a received email (rationale of the error is that the system shouldn't modify emails after they have been received, but in this scenario we are not modifying the EmailMessage, but rather adding an attachment and leaving the message as it was, so we don't want this validation to run)

Fixes AB#650461

[alexei-dobriansky]

Good Sense Reviewer - Round 1

Recommendation: Accept with Suggestions

What this PR does

This change lets email retrieval detect an already stored provider message by account and external id, return the existing inbox entry, and only add missing attachments when the caller asks for them. The lookup is centralized in the email module, and the Outlook REST API helper exits before creating a second Email Message or Email Inbox row. The attachment path avoids modifying the received Email Message while still leaving queued and sent attachment guards in place.

Problem-solution fit

Fit: Strong

The reported scenario is duplicate persistence when the same email is retrieved more than once. The diff checks for the existing inbox entry before creating records, marks and returns that entry, and handles missing attachments on a later retrieval, so it addresses the root cause instead of cleaning duplicates after insert.

Suggestions

S1 (🟠 Moderate): Cover the connector duplicate-retrieval path
Please add a connector-level regression test in the Outlook REST API test app that calls RetrieveEmails twice with the same message. It should verify that the second run returns the existing inbox entry without inserting another one, and that a second run with Load Attachments fills attachments for a message first stored without them.

Risk assessment and necessity

Risk: The regression surface is the shared email retrieval path used by apps that process Email Inbox rows, plus the new public Email Message overload used to add attachments to already retrieved messages. The queued and sent-message guards still run when inserting attachments, and there is no BaseApp event dependency.

Necessity: The change is necessary because repeated retrieval can otherwise persist duplicate inbox rows and trigger duplicate downstream processing. The scope is targeted to lookup-before-create and missing-attachment completion; the remaining gap is test coverage for the actual connector path.

---

[AI-PR-REVIEW] version=1 promptVersion=4 system=github pr=11623 round=1 by=alexei-dobriansky at=2026-09-18T22:21:15Z lastSha=d860285dc2179a849872a2b0872239e147f71a16 reviewKey=075413743ed4bb9cbf3f9ca18e38a3415b0d5319046457108fe8682388deda16 suggestions=S1@a3204f1b