1) Create a mailbox

Create a mailbox in the page "ContactManager:Mailboxes"

Just insert the desired name for the mailbox and a list of legitimate email addresses in the form "name <email>" (or just email), as well as the reply-to field.

After creating a mailbox the app redirects you to the following page:

This is the main control-panel for each mailbox, by which you can manage jobs, view/update mailbox info, folders, define rules to retrieve messages, read message headers and contents, manage conversations and contacts and compose messages.

test interactively here

2) Set mailbox credentials

Edit Manual:LocalSettings.php and create a key in the global parameter $wgContactManagerIMAP (used to receive email) and $wgContactManagerSMTP (used to send email), with the name of the created mailbox, as follows:

$wgContactManagerIMAP = [
	'mailbox_1' => [
		'server' => '',
		'username' => '',
		'password' => '',
		'port' => 993,
	],
	// ...
	
];

$wgContactManagerSMTP = [
	'mailbox_1' => [
		'server' => '',
		'username' => '',
		'password' => '',
		'port' => 465
	],
    // ...
];

("mailbox_1" should be replaced with the name of the mailbox set in the first step)

Use PHP's getenv in order to store the password as environment variables for security reasons.

Note that some email providers, like gmail and yahoo, require to create an app-password to be used instead of your regular password. Find out more

Attention Despite gmail's app password is shown with spaces after creation, it must be entered in the configuration object without, otherwise won't work !!

3) Define jobs

Press the buttons "Get mailbox info" and "Get folders" as shown below.

Note that each button is composed by the edit button on the right and the main button on the left. The first sets the button properties, and the second activates it. The first 2 buttons should be pre-filled with the mailbox name and job name, so you can activate both of them immediately. If crontab has been set correctly as shown in the install instructions, they will be executed and completed within 1-3 minutes.

By contrast, if crontab has not been set, you need to execute the following command from the command line

php maintenance/runJobs.php --type ContactManagerJob --memory-limit -1

Once that the list of folders has been retrieved from the mailbox and stored in the json-data associated to the article, press the edit button besides the primary button "Get messages", in order to set-up the related properties.

The form allows to define which folders to download from the mailbox, the local folder name, the search criteria for each folder, whether or not to retrieve message contents, the fetch method (search criteria, or by UIDs) to assign categories, check messages each n minutes, set an arbitrary number of filters for both header and messages, with related actions, and more !

It is recommended to first search messages since a specific date (for instance the last calendar year, using fetch search) and once done set fetch UIDs incremental and check email every 10 minutes) to keep your knowledge-mailbox constantly updated !!

In the first case is necessary to activate the job by pressing the main button ("Get messages") after saving the properties. In the second case is not necessary to activate the job each time since it's created each n minutes by the maintenance script activated by crontab.

All the IMAP search criteria are supported and accessible/editable through the form, for each separate folder.

• ALL
• ANSWERED
• BCC
• BEFORE
• BODY
• CC
• DELETED
• FLAGGED
• FROM
• KEYWORD
• NEW
• OLD
• ON
• RECENT
• SEEN
• SINCE
• SUBJECT
• TEXT
• TO
• UNANSWERED
• UNDELETED
• UNFLAGGED
• UNKEYWORD
• UNSEEN

An arbitrary number of filters for both headers and messages can be also set through the form in order to skip the matched messages based on a specific condition, save them to a specific path or assign one or more categories. Regexes are supported for text fields, date inputs for date fields and numeric inputs for numeric fields.

Supported filters for headers

• subject
• from
• to
• date
• message_id
• references
• in_reply_to
• size
• uid
• msgno
• recent
• flagged
• answered
• deleted
• seen
• draft
• udate

Supported filters for messages:

• id
• imapPath
• mailboxFolder
• isSeen
• isAnswered
• isRecent
• isFlagged
• isDeleted
• isDraft
• date
• headersRaw
• headers/date
• headers/Date
• headers/subject
• headers/Subject
• headers/message_id
• headers/toaddress
• headers/fromaddress
• headers/ccaddress
• headers/reply_toaddress
• headers/senderaddress
• mimeVersion
• xVirusScanned
• organization
• contentType
• xMailer
• contentLanguage
• xSenderIp
• priority
• importance
• sensitivity
• autoSubmitted
• precedence
• failedRecipients
• subject
• fromHost
• fromName
• fromAddress
• senderHost
• senderName
• senderAddress
• xOriginalTo
• toString
• ccString
• messageId
• textPlain
• textHtml
• visibleText
• attachments/id
• attachments/contentId
• attachments/type
• attachments/encoding
• attachments/subtype
• attachments/description
• attachments/name
• attachments/sizeInBytes
• attachments/disposition
• attachments/charset
• attachments/emlOrigin
• attachments/fileInfoRaw
• attachments/fileInfo
• attachments/mime
• attachments/mimeEncoding
• attachments/fileExtension
• attachments/mimeType

4) Manage mailbox

After defining the rules to retrieve messages, activating the job by pressing the main/left side of the button, and retrieving them either executing the job by command line or through crontab, the mailbox overview page will be filled interactively with retrieved headers, messages, conversations, and contacts !

Here is how it appears after a few minutes:

Despite retrieving even thousands of email headers takes only a few minutes, retrieving email contents may take many hours depending on the mailbox size and criteria/filters used

While conversations, contacts and messages are being retrieved, you can immediately categorize contacts in order to bulk-send email messages to categories, also with substitutions, and manage them as better fits your needs.

The contact page of a recipient is accessible from the following tables or pages:

• conversations
• read email (field from)
• contacts

A contact page looks as follows, to edit it press the "Edit" button as in the picture, then press "validate" and add one or more categories:

This page is created automatically by the extension based on the received and sent contacts, completed with parsed name, first and last seen dates, languages, and more.

5) Create additional mailers

A "mailer" is a program that sends email messages, that can either reside on the server (like sendmail) or be provided as a SaaS, like SendGrid, mailgun and more. Thanks to the integration with symfony mailer, ContactManager supports all the providers supported by Symfony. They can be used to send bulk email messages and they support natively templates and substitutions.

In order to create an additional mailer (either sendmail or one of the third party providers) go the page "ContactManager:Mailers", choose the provider, and assign to it a name using the following form.

Once created the page shows an editable table:

6) Set-up the credentials for the created mailer

Each mailer can use SMTP, HTTP and/or API transport, and requires its specific set of credentials, according to the following table.

(source: https://symfony.com/doc/5.x/mailer.html)

Correspondingly, ContactManager will search an object in LocalSettings.php with the following structure.

$wgContactManagerAMAZON = [
	'mailer_1' => [
		'smtp' => [
			'username' => '',
			'password' => ''
		],
		'http' => [
			'access_key' => '',
			'secret_key' => ''
		],
		'api' => [
			'access_key' => '',
			'secret_key' => ''
		]
	],
    // ...
];

// ...
$wgContactManagerSENDGRID = [
	'mailer_2' => [
		'smtp' => [
			'username' => '',
			'password' => '',
		],
		'api' => [
			'KEY' => '',
		]
	],
    // ...
];

where $wgContactManagerAMAZON is the name of the global parameter composed with uppercase name of the provider as suffix, "mailer_n" is the chosen provider name, and the required keys reflect the table above for each provider and transport.

Therefore the approach is to use an object for each provider, each of them containing one or more accounts, for better readability compared to using a single object for all of them.

Attention currently substitutions of the properties of the recipient's schema are only supported using SendGrid

7) Bulk-send email to conversation's recipients or categorized contacts

Go to the page ContactManager:Compose, select a mailbox and enter a test category (with articles corresponding to ContactManager's contacts, as explained in the 4th step, or with any VisualData's schema which includes a property of type email) in the "bcc categories" field.

The form, shown below, allows to:

• send email using different mailers
• select the from field among those registered under each mailer
• select existing recipients as to, cc, and bcc, with auto-complete, and add new recipients
• send to categories of contacts
• exclude specific recipients from a category
• select between plain-text and html (plain-text will be encapsulated in a Twig template, by contrast to html)
• select a Twig template (if content-type is text)
• add attachments (not yet tested or fully implemented)
• set offset and limit when sending to large amount of recipients

Substitutions, in the form %first_name% (based on the schema associated to each recipient) are allowed only using a mailer (currently sendgrid) since they are performed after sending the email, to avoid to send from the MediaWiki server one email for each recipient. For the same reason, substitutions of schema properties are not allowed in the Twig template, which is used as a common envelope for the body content.

The same form is also used as a popup when answering from the Inbox or sending email to the participants of a conversation !

Groups

The extension creates the following groups: (they are assignable to users through the standard special page Special:UserRights). Only users within these groups can create ContactManager's jobs, and see the UI links in the side panel. However, this does not prevent to access the relevant pages and the ContactManager namespace. If you need to protect them use Extension:PageOwnership.

The extension creates the following user rights.

Group rights