Email Configuration

This article covers configuring X2CRM for sending (and, in special cases, receiving) email.

Introduction

X2CRM provides the means to send email, natively, within the web application. Furthermore, with Professional Edition, the local MTA[[wikipedia:Message transfer agent]]: an email relay service, i.e. Postfix, QMail or Exim4. on the web server (if any) can be configured to allow X2CRM to receive emails and automatically associate them with the addressee's contact record.

Configuring SMTP Accounts

Using The Legacy (system-wide) Email Delivery Methods

Apart from using separate, third-party SMTP[[wikipedia:Simple Mail Transfer Protocol]]: a network protocol for sending email to a remote server, often involving password authentication and end-to-end SSL encryption. accounts for each user (and system purpose), there is a way to use a singular email delivery method for all emails sent via X2CRM. However, this method is not recommended, unless your web server also serves as your mail server. It is very much considered a legacy feature.

There are four options for methods of sending email, which can be found in the Outbound Email Server section in Email Settings under the Email Configuration section in the Admin page. These methods are:

1. PHP Mail
2. Sendmail
3. QMail
4. SMTP[[wikipedia:Simple Mail Transfer Protocol]]: a network protocol for sending email to a remote server, often involving password authentication and end-to-end SSL encryption.

If any of these aren't available, they won't be listed in the Method menu.

PHP Mail, Sendmail and QMail each, while independent of any offsite, third-party service, require that an MTA[[wikipedia:Message transfer agent]]: an email relay service, i.e. Postfix, QMail or Exim4. be available on the web server. The main difference is that PHP Mail uses whichever MTA[[wikipedia:Message transfer agent]]: an email relay service, i.e. Postfix, QMail or Exim4. that PHP itself is configured to use, whereas the Sendmail and QMail methods are specific to the Exim4/Postfix and QMail MTA[[wikipedia:Message transfer agent]]: an email relay service, i.e. Postfix, QMail or Exim4.'s (respectively). To use PHP Mail, you can check that PHP is configured for using an MTA[[wikipedia:Message transfer agent]]: an email relay service, i.e. Postfix, QMail or Exim4. using requirements.php.

For all instances of X2CRM Professional Edition cloud/ondemand, the methods available for sending mail include all of these except QMail.

Circumventing Spam Filters

While the non-SMTP[[wikipedia:Simple Mail Transfer Protocol]]: a network protocol for sending email to a remote server, often involving password authentication and end-to-end SSL encryption. methods for sending email within X2CRM may work immediately, a common problem encountered with them is that email goes into spam folders on the receiving end, or is not being received at all. This is especially likely to happen when the email addresses specified by users in their profiles (which get used as the sender address in the headers of mail sent by X2CRM) do not belong to the same domain name as the server hosting X2CRM. So, for example, it would be problematic if a user uses an email address in their X2CRM profile that ends in gmail.com, and the X2CRM system is hosted on example123.com

This is not a fault in X2CRM (or PHPMailer, which X2CRM uses for mail delivery). Rather, it is endemic to all web applications (i.e. Wordpress, Drupal, etc.) due to how sender address spoofing (telling the recipient that the email comes from somewhere else) is a common behavior among spammers. Furthermore, the general proliferation of email spam through various means (but especially PHP scripts running on web servers) has resulted in greatly elevated standards in the spam-detection mechanisms and heuristics of most email servers. This generally poses an entry barrier to getting around spam filters. It is thus recommended that, before sending emails using X2CRM, measures are taken to ensure that mail sent will have the best chance of avoiding spam filters.

Work-around 1: Aliasing

This works by first creating mail forwarding aliases on the server, i.e. through a Virtualmin or CPanel control interface, or manually, by editing the MTA[[wikipedia:Message transfer agent]]: an email relay service, i.e. Postfix, QMail or Exim4.'s virtual user aliases table (see their respective documentation for more information). Next, instruct all users to use these email addresses as their contact address in their X2CRM profile, so that when contacts reply, the response emails will be forwarded to the desired addresses (or even a list of addresses) specified by each alias.

For users of X2CRM Professional Edition cloud/ondemand who do not have a third-party SMTP[[wikipedia:Simple Mail Transfer Protocol]]: a network protocol for sending email to a remote server, often involving password authentication and end-to-end SSL encryption. mail service that they can use, this is the recommended method. The hosting environment has the OpenDKIM signing service running on it, and the mail server has been configured to sign all email being sent from all subdomains of x2vps.com. See the section Using DKIM for more information.

Work-around 2: Migration

This, of course, is the most straightforward solution: to use the hosting provider's email service. However, it requires switching from one's existing email service/addresses to service and addresses provided by the hosting provider, and it is also extra effort.

Work-around 3: Third-party Service

Note, using this method is not recommended; see Configuring SMTP Accounts for the preferred method of using SMTP[[wikipedia:Simple Mail Transfer Protocol]]: a network protocol for sending email to a remote server, often involving password authentication and end-to-end SSL encryption. for email delivery.

Using this method, the entire organization that uses X2CRM sends email using a single email account managed by a third-party service that supports SMTP[[wikipedia:Simple Mail Transfer Protocol]]: a network protocol for sending email to a remote server, often involving password authentication and end-to-end SSL encryption.. Thus, sending the email and digital signing are handled by the third-party service, and getting caught in spam filters generally tends to be a smaller problem.

In most cases, this method will work. How it works is that the reply-to address in the email will be set to the email address of user who is sending the mail through X2CRM, while the actual mail system user is used to authenticate with the mail server. In such cases, the address of the mail user might still show up in one of the headers of the resulting email. However, this is known to not work with many email providers, most notably GMail, which (for security and anti-spam purposes) does not permit sending emails if the sender address differs from the address associated with the Google account that was used to authenticate. If this is the case, it is recommended to use separate SMTP[[wikipedia:Simple Mail Transfer Protocol]]: a network protocol for sending email to a remote server, often involving password authentication and end-to-end SSL encryption. accounts via the credentials manager.

Using DKIM

(see main article on Wikipedia)

This method, which requires server-end configuration, is a very secure and reliable method of distinguishing email as being of legitimate and trustworthy origin. Almost every reputable email service is configured to use a mail signing agent to add a special signature sent from such addresses, in addition to checking signatures of incoming emails. Emails that are digitally signed are far more likely to be recognized by mail servers worldwide as being from a reputable source, and thus less likely to go be caught in spam filters.

However, it still requires that the sender's email address be of the same domain as the email server. That is because the sender address cannot be "spoofed", because DKIM[http://www.dkim.org/ DomainKeys Identified Mail]: a system for digitally signing email that provides the means to securely verify that the email's origin is legitimate. was designed to prevent this sort of activity (which is common among spammers). Furthermore, if outgoing email is signed for domains not corresponding to the point of origin, it may actually make matters worse; many reputable mail services (including GMail) themselves use DKIM[http://www.dkim.org/ DomainKeys Identified Mail]: a system for digitally signing email that provides the means to securely verify that the email's origin is legitimate. to avoid their domain name being abused by address spoofing. Thus, if a DKIM[http://www.dkim.org/ DomainKeys Identified Mail]: a system for digitally signing email that provides the means to securely verify that the email's origin is legitimate. signature header is added to the email, and the signature does not match the DKIM[http://www.dkim.org/ DomainKeys Identified Mail]: a system for digitally signing email that provides the means to securely verify that the email's origin is legitimate. record of the sender's domain, it will be considered a forgery attempt and blocked/filtered by most email servers.

Configuring the "Email Dropbox" For Receiving Emails

This feature, available in X2CRM Professional Edition, provides the means to automatically create contacts and email-type action records by capturing emails from external email software, i.e. Outlook and GMail. Customers of X2CRM Professional cloud/ondemand have this feature enabled and configured already. The methods for using it are as follows:

CC

When sending an email to a contact, include the email alias in the CC field.

Forward

After receiving an email from a contact, forward it to the email alias.

Direct

Send an email directly to the alias. A post in the social feed will be created using the contents of the email's body.

Setting it up requires a Linux/Unix server environment, a MTA[[wikipedia:Message transfer agent]]: an email relay service, i.e. Postfix, QMail or Exim4., and knowledge of how to set up email aliases. There are two methods of integration: direct, and via API.

Direct Integration

This method works by locally sending the email contents directly to X2CRM through the system console. It is more straightforward to configure, but requires that the MTA[[wikipedia:Message transfer agent]]: an email relay service, i.e. Postfix, QMail or Exim4. and web server hosting X2CRM be on the same machine, virtual or physical.

1. Using CPanel, Webmin/Virtualmin, or any other web host administrative tool, create a mail alias on the server that begins with "dropbox@", i.e. "dropbox@yourdomain.com". (Note: you can also do this manually by editing the mail server's configuration files, although doing that is beyond the scope of this guide.)
2. Find the absolute path on the web server's filesystem to X2CRM, if you're not sure where it is already:
   1. Paste the following into a PHP file called "path.php", in the same directory as X2CRM:

      <?php echo realpath(dirname(__FILE__)); ?>
      

   2. Navigate to the file using a web browser
   3. Record the path, append "/email.php", and use the resulting string as the path to the capture script in the mail alias.
   4. Delete the file "path.php" from the server.
3. Create an email alias. Set its destination a pipe to a program: php /path/to/x2crm/email.php (versions up to 2.5.2) or /path/to/x2crm/protected/yiic emaildropbox (versions 2.7 and later)
4. (X2CRM versions 2.7 and later) Change the permissions on the protected/runtime folder to 777 (all users can read/write).
5. Test the alias by sending a message to a fictitious name/email address (i.e. "Sue Doenimm" <test@example.com>) and CC-ing the mail alias.
6. Check in the Contacts module after sending the email, and if the fictitious contact was created, check to see that the email was attached properly to the contact record. If the contact was not created or the email was not imported, check the logs of the MTA[[wikipedia:Message transfer agent]]: an email relay service, i.e. Postfix, QMail or Exim4. for any errors.
7. Test to see if your email software's forwarded message format is supported by forwarding an email from a contact to the mail alias.

API Integration

This method works by sending the email contents to X2CRM through the remote API, and thus allows the MTA[[wikipedia:Message transfer agent]]: an email relay service, i.e. Postfix, QMail or Exim4. and X2CRM to live on different servers. Similar to the direct method, an alias will need to be constructed to receive the email and send it to a program, but in this case the program acts as a proxy by sending the contents to X2CRM via a web request. This method is more flexible, but takes more effort to set up;

1. Using your file/FTP manager of choice, navigate to the protected folder inside X2CRM, find the integration folder, and inside of that, navigate to the "MTA[[wikipedia:Message transfer agent]]: an email relay service, i.e. Postfix, QMail or Exim4." folder.
2. Download/copy emailImport.php
3. Open the file in your editor of choice, and look for the following lines of code:

   ///////////////////////////
   // Configuration details //
   ///////////////////////////
   // Set this to the IP address or domain name of the server
   $host = '';
   // Set this to the protocol (use "https://" for an SSL-enabled web server)
   $proto = 'http://';
   // Set this to the URI on the web server of X2CRM, without the trailing slash.
   // So, if the login URL is "http://example.com/x2crm/index.php/site/login",
   // this variable should be "/x2crm"
   $baseUri = '';
   // Leave this null if the host specified by $host will resolve correctly.
   // Otherwise, if in an environment where (for instance) the domain does not resolve
   // properly, and the IP address must be used, but the CRM is on a specifically-named
   // virtual host on a shared IP, set this to the domain name of that host, and set
   // $host to the IP address of the web server.
   $hostName = '';
   $data = array(
   	'user' => '',
   	'userKey' => '',
   );
   

4. Change the variables according to their comments by putting the appropriate values in the (currently empty) pairs of single quotes. For instance, if your CRM is hosted at "https://crm.domain.com/crm", you will put "https://" in for $proto, "crm.domain.com" for $host, and "/crm" for $baseUri.
5. In the $data array, set the user and userKey to the API user and API key to be used (see: Remote API: Authenticating). So, for "admin" and key "aabbccddee":

   $data = array(
   	'user' => 'admin',
   	'userKey' => 'aabbccddee',
   );
   

6. Upload the script to the server to be handling email.
7. Ensure the script has proper ownership and permissions to be run by the MTA[[wikipedia:Message transfer agent]]: an email relay service, i.e. Postfix, QMail or Exim4. user.
8. Create an email alias on the server to be handling email. Make the alias pipe to the program, /usr/bin/php /path/to/emailImport.php, replacing "/path/to" with the actual filesystem path where you uploaded the script.

Troubleshooting

If you receive a response email notifying of an unsupported forwarded message format, or do not see the email attached to the appropriate contact in X2CRM, forward the the email to X2Engine Customer Support, using the same email software that was used to test the feature. Due to the great diversity of email software and the inconsistency of forwarded/attached message formatting across platforms, the forwarded message capture may not immediately work with your email software of choice. However, per request, support for new forwarded message formats will be added in the next release. A self-service page in the Administrative console that will allow users to build patterns for recognizing their own email software is also currently in progress and scheduled for a future release.

Notes