Email Configuration - Revision history

Raymond Colebaugh at 20:05, 21 December 2015

2015-12-21T20:05:53Z

Raymond Colebaugh: /* Troubleshooting SMTP */

2015-04-03T20:54:57Z

‎Troubleshooting SMTP

Tony Zavala at 23:14, 17 July 2014

2014-07-17T23:14:00Z

Demitri: /* Direct Integration */

2014-04-18T23:11:57Z

‎Direct Integration

Demitri: /* API Integration */

2014-04-18T23:11:15Z

‎API Integration

Demitri: /* API Integration */

2014-04-18T23:10:46Z

‎API Integration

Demitri: /* Using the Email Dropbox */

2014-04-18T23:10:01Z

‎Using the Email Dropbox

Demitri: /* Email is not captured */

2014-02-13T17:53:19Z

‎Email is not captured

Demitri: /* Email is not captured */

2014-02-13T17:52:22Z

‎Email is not captured

Demitri: /* Email is not captured */

2014-02-13T17:51:40Z

‎Email is not captured

@@ Line 44: / Line 44: @@
 ;System Notification Emailer
 : Used for miscellaneous notification tasks, most notably, sending "broadcast event" emails to targeted users when users broadcast an event, select users to broadcast it to, and enable the option to notify users by email.
 = Using The Legacy (system-wide) Email Delivery Methods =

@@ Line 87: / Line 87: @@
 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 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 to avoid their domain name being abused by address spoofing. Thus, if a DKIM signature header is added to the email, and the signature does not match the DKIM record of the sender's domain, it will be considered a forgery attempt and blocked/filtered by most email servers.<ref>DKIM uses the RSA public/private key cryptographic technique to ensure that signatures are secure and cannot be forged. Thus, there is no legitimate way of circumventing this issue.</ref>
-= Troubleshooting <span class="noglossary">SMTP</span> =
+= Troubleshooting <span class="noglossary">SMTP</span> and <span class="noglossary">IMAP</span> Connectivity =
 If, when attempting to send an email, you see an error message "SMTP Error: Could not connect to SMTP host" (from an exception thrown in PHPMailer), this indicates exactly what it says; it was unable to connect. There are a wide variety of reasons why an SMTP connection should fail, but they almost always fall into one of the following two categories:
 # Configuration of the connection and authentication
@@ Line 96: / Line 124: @@
 # The option to use TLS is enabled, if required by the email service provider
 # The username and password are correct and exactly as specified by the service provider (i.e. if the SMTP username is whole email address, it should be entered as the whole email address).
 Testing the network configuration is more involved and will require logging into the server that hosts X2Engine via SSH or otherwise. One should first acquire the IP address of the SMTP host, via the command <tt>ping [smtp host]</tt> in a DOS or Unix shell, from any machine that is known to be able to access the mail server. You must then verify, locally on the X2Engine hosting server, that:
 # The SMTP host can be reached, i.e. there exists no valid network route and/or NAT rule allowing access to it, from the server on which X2Engine is hosted.
 # The SMTP hostname can be resolved (DNS is available). Try <tt>ping</tt> again, on the server hosting X2Engine itself.
-# The port number is not being blocked by the ISP for outbound connections on the port.
+# The port number is not being blocked by the ISP for outbound connections on the port. This is the case with most consumer providers, who block port 25 in an effort to block spam from infected hosts. If the first two requirements are satisfied and SMTP connections still fail, this is most likely the cause of the problem. One can also test this via port scanning or [http://www.port25.com/how-to-check-an-smtp-connection-with-a-manual-telnet-session-2/ with telnet].
-If the first two requirements are satisfied and SMTP connections still fail, this is most likely the cause of the problem. One can also test this via port scanning or [http://www.port25.com/how-to-check-an-smtp-connection-with-a-manual-telnet-session-2/ with telnet].
+# On a Linux host, check that the outbound firewall rules are not interfering. Ensure that the outbound firewall policy is to either to accept traffic, or in a more restricted environment in which the default target is to drop or reject packets, ensure that the required ports are allowed outbound. This can be verified using iptables from the command line with:
 = Configuring the "Email Dropbox" For Receiving Emails =

@@ Line 110: / Line 110: @@
 == Using the Email Dropbox ==
-As of the current version, there are three ways of using the email dropbox:
+As of the current version, there are four ways of using the email dropbox:
 ;CC
 : When sending an email to a contact, include the email alias in the CC field, and the email will be attached to the contact as an outgoing email.

@@ Line 121: / Line 121: @@
 == Direct Integration ==
-This set-up method works by locally sending the email contents directly to X2Engine through the system console. It is more straightforward to configure, but requires that the MTA and web server hosting X2Engine be on the same machine, virtual or physical.
+This set-up method works by locally sending the email contents directly to X2Engine through the system console. It is more straightforward to configure, but requires that the MTA and web server hosting X2Engine be on the same machine, virtual or physical. Furthermore, it can run into file permissions/ownership issues.
 <ol>
 <li>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.)</li>

@@ Line 139: / Line 139: @@
 == API Integration ==
-This method works by sending the email contents to X2Engine through the remote API, and thus permits the MTA and X2Engine 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 X2Engine via a web request. This method is more flexible, and it is far less likely to result in file permission issues (i.e. when the MTA attempts to run the Yii console application), but takes slightly more effort to set up. It is the recommended method to use on mulit-tenant web hosting systems
+This method works by sending the email contents to X2Engine through the remote API, and thus permits the MTA and X2Engine 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 X2Engine via a web request. This method is more flexible, and it is far less likely to result in file permission issues (i.e. when the MTA attempts to run the Yii console application), but takes slightly more effort to set up.
 For information on API authentication, see [[Remote_API#Authenticating|Remote API: Authenticating]].

@@ Line 117: / Line 117: @@
 ;Direct
 : Send an email directly to the alias, '''without "Fwd:" in the subject'''. A post in the social feed will be created using the contents of the email's body.
-;Case (coming in 4.0b)
+;Case Attachment
-: Same as forward or CC, but include a user-defined code in the email body to specify that the email should be converted to a case in the Services module.
+: Same as forward or CC, but include a user-defined code in the email body to specify that the email should be converted to/attached to a case in the Services module.
 == Direct Integration ==

@@ Line 200: / Line 200: @@
 <ul>
 <li>The domain name of the X2Engine-hosting server is resolvable on the mail host</li>
-<li>The CRM web host can be accessed from the mail host via a HTTP (web) request</li>
+<li>The host with X2Engine on it can be accessed from the mail host via a HTTP (web) request</li>
-<li>If the CRM is on a server that is behind a firewall, port 80 (or 443, if using HTTPS) on the external IP address is forwarded to the CRM's web host</li>
+<li>If X2Engine is on a server that is behind a firewall, port 80 (or 443, if using HTTPS) on the external IP address is forwarded to the X2Engine web host</li>
 <li>The API user and user key are correct in the API configuration</li>
 </ul></li>

@@ Line 194: / Line 194: @@
 In the case of API integration, substitute the "yiic" command with "/usr/bin/php /path/to/emailImport.php"; one way or another, what's happening on the most basic level is that email is getting handled by a program rather than going into a mailbox.
-If one can verify that this event happened (delivery to a local mail handling program), and no error email response is received, but the dropbox "silently" fails (by not capturing the email), verify the following:
+If you can verify that this event happened (delivery to a local mail handling program), and no error email response is received, but the dropbox "silently" fails (by not capturing the email), verify the following:
 <ul>
 <li>Your user profile email address matches the address from which you are sending email.</li>

@@ Line 192: / Line 192: @@
 <tt>Feb 10 10:28:21 HOSTNAME postfix/local[2546]: D8C0B13613CB: to=<dropbox-USER@DOMAIN>, orig_to=<USER@DOMAIN>, relay=local, delay=1.2, delays=0.86/0/0/0.39, dsn=2.0.0, status=sent (delivered to command: /home/USER/public_html/protected/yiic emaildropbox)</tt>
-If no error email response is received from the mail handling server or email service provider, but the dropbox "silently" fails (by not capturing the email), verify the following:
+In the case of API integration, substitute the "yiic" command with "/usr/bin/php /path/to/emailImport.php"; one way or another, what's happening on the most basic level is that email is getting handled by a program rather than going into a mailbox.
 <ul>
 <li>Your user profile email address matches the address from which you are sending email.</li>