> For the complete documentation index, see [llms.txt](https://docs.rubica.au/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rubica.au/households/emails/inbound-email-mapping.md).

# Inbound Email Mapping

Rubica automatically maps inbound emails to a **Primary Email Link**. This keeps email timelines grouped and reduces manual work.\
\
**Logic Summary**

```
Inbound Email
      ↓
Check Discard Rule
      ↓
Check For Existing Email Link
      ↓
Match Email Address in the Following Order (Contact → Contact Detail → Account → Lead → Institution)
      ↓
Create Email Link (Only if Match Found)
      ↓
Update Other Unmapped Emails
```

### Purpose

This automation:

* Links inbound emails to the right record (Contact, Account, Lead, or Institution).
* Discards inbound emails that match an active rule.
* Keeps Case conversations grouped under one entity.
* Backfills older inbound emails from the same sender.

### Mapping logic (in order)

{% stepper %}
{% step %}

### 1) Check discard rules

Rubica checks whether the sender matches an active **Email Processing Rule**.

If it matches:

* The email is marked as discarded.
* A reason is stored.
* Processing stops.

{% hint style="warning" %}
Discarding prevents any linking. Use it for marketing, spam, personal and automated system messages.
{% endhint %}
{% endstep %}

{% step %}

### 2) Reuse an existing Case link (when present)

If the email is attached to a **Case**, Rubica checks whether another email in that Case already has a **Primary Email Link**.

If it finds one, Rubica applies the same Primary Link.\
This keeps the whole thread mapped consistently.
{% endstep %}

{% step %}

### 3) Match the sender email address

If there is no Case link to reuse, Rubica matches the sender’s email address in this order:

1. **Contact** (standard Contact email field)
2. **Contact Detail** (Rubica Contact Detail record)
3. **Non‑Person Account** (Account Email field)
4. **Lead** (`Email` or `Email Lead Partner` field)
5. **Institution** (Primary Email field)

The first valid match becomes the **Primary Email Link**.
{% endstep %}

{% step %}

### 4) Create/update the Email Link record

Rubica creates an **Email Link** record and updates the **Email Message** with the Primary Link.

Rubica also stores a short match reason, like “Contact email match”.\
This is the fastest way to audit what happened.
{% endstep %}

{% step %}

### 5) Backfill other unmapped emails

After mapping the new email, Rubica checks for other unmapped emails from the same sender.

If it finds any, it applies the same Primary Email Link. This cleans up historical inbound email automatically.
{% endstep %}
{% endstepper %}

### What gets recorded (Email Link)

Each **Email Link** record stores:

* Email Message ID
* Linked record ID (Contact / Account / Lead / Institution)
* From Address
* Message Date
* Flow automation GUID
* Match reason

### When no match is found

If there is no discard match, no Case link to reuse, and no sender match, the email stays **unlinked**.\
It remains available for manual review.

### When an email is discarded

An email is discarded when it matches an active **Email Processing Rule**. For example:

* Rule applies to **To & From Email Address**
* `Scope = All Users`
* `Active = True`
* Sender matches the rule value

When discarded:

* `Is Discarded = True`
* Discard date/time is recorded
* Discard reason is stored

### Troubleshooting

If an email didn’t link as expected:

1. Confirm the sender email matches what’s stored (exact value).
2. Check for duplicates. Multiple records can share one address.
3. Confirm the relevant Contact Detail is not archived.
4. Check whether a discard rule applied.
5. Open the **Email Link** record and review the stored match reason.