Email::Store::Entity - People in the address universe

   my ($name) = Email::Store::Name->search( name => "Simon Cozens" )
   @mails_from_simon = $name->addressings( role => "From" )->mails;

This file defines a number of concepts related to the people who send and receive mail.

An "entity" is a distinct "person", who may have multiple friendly names and/or multiple email addresses.

We save distinct names and addresses; these are tied to mails by means of "addressings". An addressing has a name, an address, a mail, a role and an entity. The entity ID is meant to distinguish between the same person with different email addresses or the same email address replying on behalf of several names; see http://blog.simon-cozens.org/6744.html for more on this theory.

There are many heuristics to determine whether foo-bar@example.com (Foo Bar) is the same person as foo@example.com (Foo), or the same person as foo-bar@anotherdomain.com (Foo Bar), or an entirely separate individual. Email::Store only knows one such heuristic, and it's not a good one: it believes that a combination of email address and name represents a distinct individual. It doesn't know that simon-nospam@ and simon@ the same domain are the same person. This heuristic is implemented by Email::Store::Entity::Correlator::Trivial.

However, in the same way as the rest of Email::Store, you can write your own correlators to determine how an addressing should be allocated to an entity.

A correlator must live in the Email::Store::Entity::Correlator namespace, and implement the get_person_order and get_person methods. get_person is called with a reference to the currently-selected entity and also the mail object, role name, and name and address objects involved. By examining the mail and the current list of addressings, your method can choose to find or create a more appropriate entity, and replace the reference accordingly.