Let the platform do the work
SugarClubContact+1 (877) 842-7276

Troubleshooting Outbound Email Using Command Line

Overview

When emails are failing to send from Sugar, there are a variety of potential causes. Please refer to the article Troubleshooting Outbound Email Using Sugar Logs to discover which error messages your email server is returning. If you cannot resolve the issue based on this top-level error message, you can connect to the email server via command line to see precisely what is failing. This testing method typically provides a more granular error message that can help resolve the issue.

Prerequisites

This article will detail using telnet and OpenSSL to test your email server. These tests should preferably run from the same server that is hosting your Sugar instance, though connecting from a different server may still be useful in diagnosing the issue. Telnet and OpenSSL should be available for use on your Linux server. If your Sugar instance is hosted on a Windows server, you may need to refer to an external article for instructions to install OpenSSL such as Building a Web Server for Windows, which is written for email servers that use SMTP with TLS/SSL. 

Steps to Complete

Refer to the appropriate section below to test your email server.

SMTP

From a telnet prompt, type the following commands:

  1. O smtp.yourserver.com port#, for example O smtp.office365.com 25, and then press "Enter".
  2. EHLO then press "Enter".
    • If this step throws an error, you may not be able to send emails from the domain you have specified. Some email servers allow you to send from multiple domains while others do not. Contact your email server administrator is you are receiving an error on this step and are attempting to send from multiple domains.
  3. AUTH LOGIN then press "Enter".
    • The server response should be VXNlcm5hbWU6. This string of characters is encoded in a base64 scheme that translates to "Username:". Convert your username to base64 using a base64 converter and type in your encoded username. If you do not receive that string of characters and instead receive an error message, simple authentication may not be enabled on your email server, which could be the reason you are having email problems with Sugar. Ask your email administrator to enable simple authentication on the SMTP server and try this test again.
    • After entering your encoded username, the server response should be UGFzc3dvcmQ6. This string of characters is encoded in a base64 scheme that translates to "Password:". Convert your password to base64 using a base64 converter and type in your encoded password. 
    • In the example in the Sample Telnet Testing section, the final line shows that we could not authenticate on the email server. If you receive this error message, you likely have invalid credentials or your base64 conversion for either the username or password was incorrect. Test one more time to be sure, and then reset the account credentials.
  4. MAIL FROM:sender@domain.com then press "Enter".
    • If the sender is not permitted to send mail, the SMTP server returns an error. This sometimes occurs when you log in with a valid username but attempt to send emails using a different From address. For example, if you log in with jim@mydomain.com, but attempt to send an email with a From address of joe@mydomain.com, your email server might not allow it. This sometimes shows up in the Sugar log as an invalid From address error depending on your server response codes.
  5. RCPT TO:recipient@remotedomain.com then press "Enter".
    • If the recipient is not a valid recipient or the server does not accept mail for this domain, the SMTP server returns an error.
  6. DATA then press "Enter".
    • If you made it this far, you should be able to send a test email to yourself. Enter a string of characters. When you are done, type a period (.) on a line by itself and then press "Enter". This should queue the email to send. Check the email account that you chose to send the test email to in a few minutes and it should be there if things are functioning correctly.

Sample Telnet Testing

Note: User input is in red text. Full IP addresses and domains have been omitted.

  user$ telnet
telnet> o mail.xxxx.com.au 25
Trying 202.xxx.105.xxxx.
Connected to mail.xxx.com.au.
Escape character is '^]'.
220 mail.xxx.com.au Microsoft ESMTP MAIL Service ready at Mon, 9 Jul 2012 21:32:58 +1000
ehlo xxx.com
250-mail.xxx.com.au Hello [71.xxx.22.xxxx]
250-SIZE 104857600
250-PIPELINING
250-DSN
250-ENHANCEDSTATUSCODES
250-STARTTLS
250-AUTH LOGIN
250-8BITMIME
250-BINARYMIME
250 CHUNKING
auth login
334 VXNlcm5hbWU6
bxlfdXNlcm5hbWU=
334 UGFxc3dvcmQ6
bxlfcGFzc3dvcmQ=
535 5.7.3 Authentication unsuccessful

SMTP with TLS/SSL

Secure connections require a different connection method with a few different parameters. Please refer to the Configuring IP Addresses, Ports, and Domains article for common email port numbers.

From a telnet prompt, type the following commands:

  1. openssl s_client -starttls smtp -crlf -connect smtp.yourserver.com port#, for example openssl s_client -starttls smtp -crlf -connect smtp.office365.com:587 and then press "Enter".
    • If a connection is successful, and the certificate is valid, you should see a very long string of characters scroll past on the screen.
    • If your email server rejects the –starttls parameter, simply omit it to initiate an SSL/SSLv2/SSLv3 connection instead.
  2. ehlo and then press "Enter".
    • If this step returns an error, you may not be able to send emails from the domain you have specified. Some email servers allow you to send from multiple domains while others do not. Contact your email server administrator if you are receiving an error on this step and are attempting to send from multiple domains.
  3. auth login and then press "Enter".
    • The server response should be VXNlcm5hbWU6. This string of characters is encoded in a base64 scheme that translates to "Username:". Convert your username to base64 using a base64 converter and type in your encoded username. If you do not receive that string of characters and instead receive an error message, simple authentication may not be enabled on your email server, which could be the reason you are having email problems with Sugar. Ask your email administrator to enable simple authentication on the SMTP server and try this test again.
    • After entering your encoded username, the server response should be UGFzc3dvcmQ6. This string of characters is encoded in a base64 scheme that translates to "Password:". Convert your password to base64 using a base64 converter and type in your encoded password. 
    • If you receive an error message, you likely have invalid credentials or your base64 conversion for either the username or password was incorrect. Test one more time to be sure, and then reset the account credentials.
  4. mail from:sender@domain.com and then press "Enter".
    • If the sender is not permitted to send mail, the SMTP server returns an error. This sometimes occurs when you log in with a valid username but attempt to send emails using a different From address. For example, if you log in with jim@mydomain.com but attempt to send an email with a From address of joe@mydomain.com, your email server might not allow it. This sometimes shows up in the Sugar log as an invalid From address error depending on your server response codes. Please note that the server used in this example requires the email address to be encapsulated, otherwise a syntax error will be thrown.
  5. rcpt to:recipient@remotedomain.com and then press "Enter". 
    • If the recipient is not a valid recipient or the server does not accept mail for this domain, the SMTP server returns an error.
  6. data and then press "Enter". 
    • If you made it this far, you should be able to send a test email to yourself. Enter a string of characters. When you are done, type a period (.) on a line by itself and press "Enter". This should queue the email to send. Check the email account that you chose to send the test email to in a few minutes and it should be there if things are functioning correctly.

Sample OpenSSL Testing

Note: User input is in red text. Full IP addresses and domains have been omitted.

  user$ openssl s_client -starttls smtp -crlf -connect smtp.gmail.com:587
CONNECTED(00000003) 
depth=1 /C=US/O=Google Inc/CN=Google Internet Authority
verify error:num=20:unable to get local issuer certificate
 verify return:0
 ---
 Certificate chain
  0 s:/C=US/ST=California/L=Mountain View/O=Google Inc/CN=smtp.gmail.com
  i:/C=US/O=Google Inc/CN=Google Internet Authority
  1 s:/C=US/O=Google Inc/CN=Google Internet Authority
  i:/C=US/O=Equifax/OU=Equifax Secure Certificate Authority
 ---
 Server certificate
 -----BEGIN CERTIFICATE-----
 MIIDWzCCAsSgAwIBAgIKFeQVggADAAA7NjANBgkqhkiG9w0BAQUFADBGMQswCQYD
 VQQGEwJVUzETMBEGA1UEChMKR29vZ2xlIEluYzEiMCAGA1UEAxMZR29vZ2xlIElu
 dGVybmV0IEF1dGhvcml0eTAeFw0xMTExMTgwMTU3MTdaFw0xMjExMTgwMjA3MTda
 MGgxCzAJBgNVBAYTAlVTMRMwEQYDVQQIEwpDYWxpZm9ybmlhMRYwFAYDVQQHEw1N
 b3VudGFpbiBWaWV3MRMwEQYDVQQKEwpHb29nbGUgSW5jMRcwFQYDVQQDEw5zbXRw
 LmdtYWlsLmNvbTCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEAuK+t5ZRq6c3K
 kWPwLuIcPa6DgiBURaQK9akP4OBoXKJ6bqYIQWsS4C3RgnOaGaDENadxHSNZ5Qpl
 Vqg2S54N54SM5OXwOq0NtrqdlbhgigB53TZouiJvnLDxxIexSOn2Gx1qyZF2z8Ii
 MoUhHuStWgW5YoOHje8z6K9xQdYkQp0CAwEAAaOCASwwggEoMB0GA1UdDgQWBBTs
 OL4jbtJ5l8B6/eoEvv30KEiTrjAfBgNVHSMEGDAWgBS/wDDr9UMRPme6npH7/Gra
 42sSJDBbBgNVHR8EVDBSMFCgTqBMhkpodHRwOi8vd3d3LmdzdGF0aWMuY29tL0dv
 b2dsZUludGVybmV0QXV0aG9yaXR5L0dvb2dsZUludGVybmV0QXV0aG9yaXR5LmNy
 bDBmBggrBgEFBQcBAQRaMFgwVgYIKwYBBQUHMAKGSmh0dHA6Ly93d3cuZ3N0YXRp
 Yy5jb20vR29vZ2xlSW50ZXJuZXRBdXRob3JpdHkvR29vZ2xlSW50ZXJuZXRBdXRo
 b3JpdHkuY3J0MCEGCSsGAQQBgjcUAgQUHhIAVwBlAGIAUwBlAHIAdgBlAHIwDQYJ
 KoZIhvcNAQEFBQADgYEAQiMlHuQLRFqR10UsSg5WTNe3vagbdnBLAkdhvAf90B5a
 9beBxJH2/ylTSIGfD2uceAqzcsQe6Ouy4C9r3rz86qA1dhdtIcPg6uoZb+E2qhE5
 UaOJOPO4rHInX9kscBxh+baHbpBMh+ch6v5L8plss8hd0id8C4g10YKzwcgPYlQ=
 -----END CERTIFICATE-----
 subject=/C=US/ST=California/L=Mountain View/O=Google Inc/CN=smtp.gmail.com
 issuer=/C=US/O=Google Inc/CN=Google Internet Authority
 ---
 No client certificate CA names sent
 ---
 SSL handshake has read 1915 bytes and written 351 bytes
 ---
 New, TLSv1/SSLv3, Cipher is RC4-SHA
 Server public key is 1024 bit
 Secure Renegotiation IS supported
 Compression: NONE
 Expansion: NONE
 SSL-Session:
  Protocol : TLSv1
  Cipher : RC4-SHA
  Session-ID: EB5A90D0F3A7BC23B76ECCD53CE684645C189AA72BBFCBB3F44826AED543A387
  Session-ID-ctx:
  Master-Key:
EFE34F5E147D4F4EF81CFD7324F51681D0E1CE64CD0324871992EA1815F0E0DFB3D77918400DA39D0FB9CA8E438E1BD2
  Key-Arg : None
  Start Time: 1342619312
  Timeout : 300 (sec)
  Verify return code: 0 (ok)
 ---
 250 ENHANCEDSTATUSCODES
ehlo gmail.com
 250-mx.google.com at your service, [71.207.122.147]
 250-SIZE 35882577
 250-8BITMIME
 250-AUTH LOGIN PLAIN XOAUTH
 250 ENHANCEDSTATUSCODES
auth login
 334 VXNlcm5hbWU6
bXluYW1l
 334 UGFzc3dvcmQ6
bXkgcGFzc3dvcmRz
 235 2.7.0 Accepted
mail from: xx@gmail.com
 250 2.1.0 OK gs4sm11095517qab.16
rcpt to: yy@gmail.com
 250 2.1.5 OK gs4sm11095517qab.16
data
 354 Go ahead gs4sm11095517qab.16
This is the body of the email. To stop entering data into the body, type a . on a line by itself.
.
 250 2.0.0 OK 1342619507 gs4sm11095517qab.16
quit
 221 2.0.0 closing connection gs4sm11095517qab.16
 read:errno=0