Understanding WP Issues CRM Email Version 3.4 and above


Essentially WP Issues CRM is an email client, an email list manager and a CRM combined in one, using all of the classification power of WordPress.

The email function supports the automated handling of high volume repetitive incoming correspondence and facilitates follow-up correspondence on issues.

It parses the body text of incoming emails to extract name and street address information (commonly included in political advocacy emails) and match that information to your constituent database.

It supports automated reply to learned subjects or texts and automated classification of messages for record keeping.

Basic Concepts

The major data concepts in WP Issues CRM are:

  • Constituents
  • Issues ( these are just WordPress posts and can be public or private )
  • Activities (which are always linked to a constituent and an issue)

An incoming email is logged as an activity — you may wish to delete it without logging it, but if it comes from a constituent, you can “Record” it, automatically logging it as an activity for a constituent pertaining to an issue. You would use the Record email button when you wanted to save the message for future action.

If you have a reply ready, you can just quickly reply and, if it the message does not pertain to a recurring issue and you do not wish to create an issue for it, the email will be assigned to “Unclassified Activity.”

If it looks like the email might be part of an incoming email campaign, one of many repetitive messages to come, you can automate future replies as follows.

  1. Select or create an Issue to assign the email to — one-click on the + sign to add a new issue and assign it.
  2. Draft your reply and Save it — this will become the standard reply for that issue/pro-con combination.
  3. When you reply, click “Train” on the confirmation popup.  Training sets the relationship between incoming subject and issue/pro-con classification.  The reply for that issue/pro-con combination can be edited.
  4. Future messages with the same subject line and the same main content can then be recorded and replied to with one click on the sweep (>>) button on the inbox.
  5. Note that if you already have a lot of identical messages in your inbox, you may need to wait a few seconds and refresh the inbox for the messages to come up as grouped and ready for sweeping.

Even if you do not click “Train”, your saved reply will be available for loading when you assign another incoming email to the same issue/pro-con combination.  You will not be offered the option to train unless you have saved or loaded a standard reply (except in the rare case where you have deleted a standard reply for a previously trained message).

Grouping Control

Grouping control determines when messages are grouped for bulk handling in the inbox. It resembles the “Conversation View” choice in many email clients, but is completely different.  It does not group messages from cc’d users in reply threads, rather it groups similar incoming messages from unrelated users to be handled in bulk.

By default WP Issues CRM takes a conservative approach to grouping — grouping messages only if you have checked train on a previous reply AND the messages:

  1. Have the exact same subject line (binary, down to capitalization and spaces, as when the messages are being generated by clicks on an advocacy website) AND
  2. The messages are reasonably long — over 200 words (1400 nonspace characters at 7 characters per word) AND
  3. The message content is 85% identical (excluding address blocks in the body).

You can loosen the second and third criteria to group more messages.  You might want to do this temporarily when using a wildcard subject line that matches multiple similar subjects to clean up messages in a campaign that is using multiple subject lines.  You can access the Grouping Control tab through Settings on the email menu.


Trained subject lines and standard replies for issues typically need to evolve over time.  In addition to simply remapping subject lines and/or creating new replies in the main reply editor, you have three tools:

  1. You can set a “Forget Date” in email settings.  Older mappings will simply be ignored.
  2. You can directly manage the Subject list.
  3. You can directly manage the Saved reply list.

Wild Card Subjects and Informal Campaigns

The easiest campaigns to manage with WP Issues CRM are those generated by computers — constituents are urged to click to contact their legislator.  These campaigns often result in a flood of emails with identical subject lines and identical non-address content.  Less formal campaigns where the email subject and content can change slightly are more work.

You may need to manually review each message in an informal campaign to classify it to the issue that is the subject of the campaign.  But, once you classify the message, WP Issues CRM will prompt you to load your standard reply for that issue/pro-con combination.  You can then further personalize that reply before sending it.

In campaigns that are semi-formal (i.e., are computer generated, but with some variation in subject line and content), you may be able to fully automate responses to them as follows:

  1. Through the Subjects list add a wildcard subject line that matches most of the subject lines.  For example, if the campaign were about a particular numbered piece of legislation (H2389), you could create a wildcard line like %2389%.
  2. Return to the Inbox and create and save a standard reply to one of the messages.
  3. Reply to that message and click Train.
  4. Go to Settings and lower the length and matching standards under Grouping Control
  5. Return to the Inbox once again and the messages should be grouped (note that grouping will take a few seconds as the Train action in step 3 spins off a longer task to review the Inbox messages and see if they can be handled).
  6. If messages aren’t grouped, try lowering the length and matching standards even further and also check they way you defined your Wildcard subject.

Caution: Wildcard subject lines can match way too much, so it is good practice to delete them after you’ve handled campaign you designed them for.

Inbox and Outbox

Because accessing your email inbox across the internet is slow, WP Issues CRM creates a local image of your inbox on your WordPress server. It does so in two stages: First it synchronizes the list of the messages. Second it collects the details for each message — the second process is much slower, but it only needs to be done once and happens continuously as messages come in.  WP Issues CRM develops suggestions about issue and constituent mapping as it parses. The Inbox you see in WP Issues CRM is derived from the local image.   Every two minutes, your WP Issues CRM Inbox is synchronized to the underlying email inbox on your email server.

Conversion to 3.4 from Earlier Versions of WP Issues CRM

The upgrade from earlier versions to version 3.4 requires you to resave any standard reply templates you have developed manually.  There is a fundamental logic change in version 3.4.  In previous versions, reply templates belonged to subject lines.  Since many subject lines could correspond to a single issue, this created an artificial multiplication of templates.  In 3.4, reply templates are associated with issue/pro-con combinations.  For most users, this will be a healthy process of house cleaning — standardized replies need to be upgraded routinely anyway.

The upgrade also rebuilds the WP Issues CRM outgoing queue and if you do the upgrade while outgoing messages are pending in the outbox, those messages will be stranded, although not lost.

If you have a large set of standardized replies and need assistance converting or if you feel you may have stranded outgoing messages that you cannot easily reconstruct, we can help — send an email to help@wp-issues-crm.com.

Version 4.0  no longer supports use of |*first_name*|.  Use of first name and last name tokens creates too many risks of errors (nobody calls me Suzanne, my name is Sue) — much safer to just jump into the message, rather than start with a possibly incorrect salutation.

Technical Note on the Logic of Training and Grouping

You should generally be able to just go with the  flow of suggestions offered by WP Issues CRM.  However, for those interested in understanding how that flow is generated, here are some notes about the rules governing the process.

  • The inbox only groups messages if they look like messages that have previously been acted on — recorded or replied to — and Train was checked when the action was taken.
    • The subject line is binary identical to a previously trained message ( or matches a wildcard subject defined in Subjects ) AND
    • The content matches a previously trained message at the level required in Settings
      • The required percentage of sentences (by character count) match AND
      • The message is long enough
    • The subject line and content matches must agree as to what issue/pro-con combination they point to
    • The inbox will ungroup otherwise groupable messages if the sender addresses do not parse at the accuracy level required in settings
    • See code in WIC_Entity_Email_Inbox::load_inbox in wic-entity-email-inbox.php
  • The option to Train is offered at the time a message is recorded or replied to only if:
    • Issue has been assigned and a reply standard has been saved or loaded since the issue was assigned OR
    • You are only recording not replying — in this case, if there is no reply template, when you sweep, messages will be recorded, but not replied to OR
    • The count of messages in the current subject line is greater than one — in other words, the messages meet the requirements above for grouping (they had to have been previously trained)
    • See code in wpIssuesCRM.processEmail in email-process.js.
  • When Train is checked and a message is submitted to reply or record, the processor (WIC_Entity_Email_Process::handle_inbox_action_requests in wic-entity-email-process.php ) saves two mappings:
    • A single mapping of subject line (binary exact) to issue/pro-con combination (WIC_Entity_Email_Subject::save_new_subject_line_mapping in wic-entity-email-subject.php) — subject lines from future messages will be mapped using the most recently saved (matching) subject-line mapping to an issue/pro-con combination.
    • For each sentence in the message (excluding sentences recognized as addresses) a mapping of that sentence to the issue/pro-con combination (WIC_Entity_Email_MD5::create_md5_map_entries in wic-entity-email-md5.php).  Sentences in future messages will be individually compared to previously mapped sentences and the issue/pro-con combination getting the most sentence votes from the most recently mapped matches (weighted by sentence length) will be assigned (WIC_Entity_Email_MD5::get_issue_and_pro_con_map_from_md5 in wic-entity-email-md5.php).
    • As noted above under grouping, mappings are used only if the subject map agrees with the sentence map.
  • Only messages meeting the criteria above for grouping will be flagged as sweepable.  When you click the >> sweep button, all sweepable messages are sent to the server for processing:
    • They will be recorded to their last mapped issue/pro-con.  If they have been unmapped (by another instance someone else has open), they will be bypassed and still available for processing upon inbox refresh.
    • If there is no saved reply template for their last mapped issue pro-con, they will only recorded
    • If there is a saved reply template for their last mapped issue pro-con, that reply will be generated.
    • See code in WIC_Entity_Email_Process::handle_inbox_action_requests in wic-entity-email-process.php.
  • Some consequences of these rules are:
    • Messages are never grouped in the inbox until one of the matching group has been trained
    • Message grouping is conservative — this may mean a few more clicks in some cases, but minimizes risk of replying incorrectly.
    • When you make a quick reply to a message without saving or using a standard reply, you are not offered the option to train (and, in fact, are not required to confirm the action)
    • You can train messages without replying — this supports a work flow of accumulating messages for later reply.
    • If you train a message for sweeping with a reply, but later delete the reply from the Saved list, then sweeping will record matching without replying to them.

Leave a comment

Your email address will not be published. Required fields are marked *