Hook to determine what contacts an Activity gets attached to in EmailProcessor

Currently in EmailProcessor, we create / find contacts for ALL the addresses in the email header. The activity is then created with those contacts. Clients cannot control when/where/how contacts are created.

One easy work-around with minimal changes is to use a hook which is called once per email address found in the headers that the site can then override with their specific needs:

hook_civicrm_EmailProcessorContact( $emailAddress, $contactID, &$result )

inputs:
$emailAddress is the email address we're currently processing
$contactID is the id that was found as a match, or null if no match found
outputs:
$result is an array with two values: a contactID and an 'action'

action can be one of:

• Create new individual (i.e. use the found contactID or create new contact if needed) EMAILPROCESSOR_CREATE_INDIVIDUAL
• Use the returned contactID(s) instead: EMAILPROCESSOR_OVERRIDE
• Ignore this email address: EMAILPROCESSOR_IGNORE

As part of this issue, we will also implement an instance of this hook for the Physician Health Program's needs described below:

// Orgs with this tag will always have same-domain emails filed on them, even if an individual matches. Examples are orgs with a frequently rotating account rep.
const FILE_TO_ORG_ALWAYS_TAG='MyTag1';

// Orgs with this tag will have same-domain emails filed on them only if it passes through the ALWAYS tag check without finding a match, AND it does not match an individual.
const FILE_TO_ORG_INDIVIDUAL_UNMATCHED_TAG='MyTag2';

If FILE_TO_ORG_ALWAYS_TAG is set THEN
If domain portion of this email matches domain portion of an org contact with tag=FILE_TO_ORG_ALWAYS_TAG then
$result = array( 'action' => EMAILPROCESSOR_OVERRIDE, 'contactID' => [the org's contact id]));
return;
END IF
END IF

IF full email address matches an individual contact's email
$result = array( 'action' => EMAILPROCESSOR_OVERRIDE, 'contactIDs' => [the individual's contact id] );
return
END IF

// So at this point we are now only processing ones where it has neither matched an org with the FILE_TO_ORG_ALWAYS_TAG nor an individual email.
// So we look for the second tag for this class of orgs.

IF FILE_TO_ORG_INDIVIDUAL_UNMATCHED_TAG is set THEN
If domain portion of this email matches domain portion of an org contact with tag=FILE_TO_ORG_INDIVIDUAL_UNMATCHED_TAG then
$result = array( 'action' => EMAILPROCESSOR_OVERRIDE, 'contactIDs' => [the org's contact id] );
return
END IF
END IF

// If we get here, $result = array( 'action' => EMAILPROCESSOR_CREATE_INDIVIDUAL )