KBA-01532: Processing Inbound Emails Overview


How does the Spitfire Project Management System process inbound emails?


First, Spitfire examines the email to determine if it is

  • A reply to a document routed email (see KBA-01254).
  • A disposition notice (mail undeliverable, fax notifications, etc.).
  • A delivery notice (mail has been delivered, mail has been read, etc.).
  • General email

General Emails

For general email, the system will first examine the sender of the email and compare it to the whitelist setting in ICTool.  The system can be configured to reject all general email, to accept all general email, or to accept email only from known contacts or from recognized companies (set up as ‘@company‘). The final whitelist option allows MaryTheNewHire@acmeplumbing.com to send email to Spitfire successfully as long as Spitfire has exactly one primary contact using @acmeplumbing.com email addresses.

If the sender passes the whitelist, the subject is scanned from left to right looking for a Project ID.  The Project ID may have dashes or not.  For example, both of these subjects will find GC-003:

  • Re: Change in schedule for GC003
  • Fw: GC-003 delayed by power outage

If no Project ID is recognized, the system will see if the sender of the email is associated with exactly one active project team.  If so, that project will be assumed (but no other scanning of the subject line is performed).

After successfully finding a Project ID in the subject, the system looks for the Doc Type. Only Doct Types that have EMailText DirectInbound Yes or Smart are considered.  If no project is resolved, then document types that require a project are not considered.  Finally, only when the mode is “Yes” can a new document be created.  See the section below on Document Type Names in subject Lines.

Examples to create a new Spitfire document:

  • Fw: GC003 Safety Notice; fuel oil spill
  • GC003 Field Report: 9/18/2012

If a new document is created, the following fields are set:

  • The title is set to the first 60 characters of the subject
  • The source contact is set to the primary contact associated with the email sender‘s domain
  • The responsible party is set to the contact associated with the sender‘s email address
  • For Correspondence documents, the subtype is set to EM (Inbound Email)

If no Doc Type is recognized, Correspondence is assumed and a new Correspondence document is created.

IMPORTANT NOTE: If the Correspondence Doc type is not active (or the EM subtype is not defined) the inbound general email will be rejected.

Example to attach your email to an existing Spitfire document:

  • Re: GC003 Field Report # 0146 Photos
  • Re: GC003 CCO # 0150.0006 HVAC additional CFM

If the pound/hash mark is used to end the Doc type, and the immediately following word is numeric (see 0146 above), the system will check for a specific document and associate the email with the matching document rather than create a new document.

Updates to the Route

When an email is received for an existing document, sfPMS will update the route. Assuming sfPMS can resolve the sender of the email to a specific contact, the current route of the document is checked. If the email sender is in the current route sequence, the email is used as a response to that route, and any parallel route groups are resolved. Otherwise, the sender of the email is ADDED to the document route BEFORE the current route sequence by pushing the current sequence DOWN.

Next, every TO address on the email is checked and if a corresponding contact exists in sfPMS, they are added to the NEXT sequence in the route, merging with any existing route to form a parallel group.  If the email is neither from nor to the responsible party, the responsible party is also added to the group so they will be aware of the change to the document. Finally, if the email is from an internal contact and the route ends after the email recipients, then the email sender is added to the bottom of the route to form a round trip (so they will get notified when the email is answered).


  • CC’d recipients on the EMail do not update the document route. (Because no response from them is expected)  If they do reply all, their response will be inserted into the route as above.
  • The Destination sequence is never used by direct inbound, even if the destination party is the one and only named recipient on the email.

Reply Emails

The exact document is already known when the inbound email is a reply to a document route.  The system updates the corresponding route row on the document in addition to processing the attachments as described in the next section.

Attachment Handling

For all emails received (both general and replies), the system will consider cataloging the email attachments as well as the email itself.  See KBA-01260 for information about which attachments are considered eligible as well as KBA-01265 for the FileCatalogConfig|InboundEmail:ext rule.   Note that the inbound email is associated with the EML file type.  For EML files to be catalogued, a target folder must be specified in ICTool and the FileCatalogConfig|InboundEmail:eml rule must have a result value of 1 or 2 for the corresponding Doc type.

Document Type Names

The system will attempt to recognize a Doc type based on all or part of its name in the subject.  If many Doc types are enabled for inbound email, or Doc types have long names or similar names (such as Customer Bid, Invitation to Bid and Vendor Bid Request, etc.) then the system may need unnaturally long email subjects just to specify the type.  Keep inbound email Doc types to a reasonable set.  Also consider using the DocTypeConfig | EmailShortID rule to specify a unique subject ID, such as Inv2Bid for Invitation to Bid.  Note that once a Doc type has a short ID, the short ID must be used on all emails for that Doc type.

Additional Comments:

See KBA-01263 for information on setting up the system for inbound email processing (the email account, etc) and KBA-01531 for notes about improving the handling of unsolicited emails.

KBA-01532; Last updated: September 20, 2017 at 12:25 pm;