[28.2] 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

• A new centralized FindRetrievedEmail on the email module lets connectors check whether an email had been retrieved before, 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)

Note

In this version the Email - Outlook REST API app does not live in BCApps, so this PR carries the System Application part only. The consuming change in the Outlook connector (Email - Outlook API Helper) has to be done in the NAV repository for this branch.

Fixes AB#650461

[alexei-dobriansky]

Good Sense Reviewer - Round 1

Recommendation: Request Changes

What this PR does

This change adds a shared lookup for previously retrieved emails, adds an Email Inbox key, and exposes an attachment overload that can add missing attachments to a received email without modifying the email message. The direction matches the shared email module layer, but the current implementation does not make duplicate creation safe under concurrent retrieval and leaves the attachment guard controlled by a caller-provided flag.

Problem-solution fit

Fit: Partial

The code fits the sequential duplicate-retrieval case and adds the shared API pieces needed by the branch. It does not make the duplicate check atomic, and the user-visible retrieval path still depends on the connector-side change in the branch that owns the connector.

Suggestions

S1 (🔴 High): Make the duplicate lookup atomic
The new lookup reads committed rows with a non-unique key, so two retrieval sessions can both miss the row and insert duplicates. Add an atomic guard, such as locking the lookup/insert path or enforcing uniqueness for the account and external message id. This keeps the same duplicate bug from returning under concurrent retrieval.

S2 (🔴 High): Validate the attachment bypass inside the implementation
The new public overload lets any caller pass true and skip the Modify() guard for retrieved messages. Derive the bypass from the actual inbox state, or reject it unless the message is an already retrieved message that is only receiving missing attachments. This keeps received email messages immutable outside the intended recovery path.

Risk assessment and necessity

Risk: This area stores retrieved email metadata and customer attachments, and the new methods are public System Application surface. The current CI run also failed the System Application builds in an unchanged file, so I did not anchor that as a code suggestion, but the branch still needs a clean build before merge.

Necessity: Avoiding duplicate inbox entries is important because repeated retrieval should not create extra stored emails. The shared API is useful, but it needs the concurrency and guard checks above so the fix does not leave the same data-integrity problem open or weaken received-email immutability.

---

[AI-PR-REVIEW] version=1 promptVersion=4 system=github pr=11618 round=1 by=alexei-dobriansky at=2026-09-18T22:37:33Z lastSha=461ae525cff484ca965ee52c066d770025917dbd reviewKey=ac13362b946fdf28d47d7bbcf60d3644bb1c38f9920de425c144b012a3e285ee suggestions=S1@2bd923b0,S2@e3e04252