<email:imaps-connection host="..." user="..." password="..." >
<email:properties >
<email:property key="mail.debug" value="true" />
</email:properties>
</email:imaps-connection>
Troubleshooting Email Connector - Mule 4
To troubleshoot Anypoint Connector for Email (Email Connector), become familiar with the information about app logs, JavaMail debugging, troubleshooting access attachments, troubleshooting protocols issues, and interpreting commonly thrown messages.
View the App Log
If you encounter problems while running your Mule runtime engine (Mule) app, view the app log as follows:
-
If you’re running the app from Anypoint Platform, the output is visible in the Anypoint Studio console window.
-
If you’re running the app using Mule from the command line, the app log is visible in your OS console.
Unless the log file path is customized in the app’s log file log4j2.xml
, view the app log in the default location MULE_HOME/logs/<app-name>.log
.
Enable JavaMail Debug Logging
JavaMail debugging logging is used by underlying third-party classes.
To enable JavaMail debugging logging:
-
Access Anypoint Studio and navigate to the Package Explorer view.
-
Open your application’s project name.
-
Open the
src/main/mule
path folder. -
Open your Mule app XML file inside the folder.
-
Add the
<property key="mail.debug" value="true"/>
to the IMAP or SMTP connection element. -
Save your changes.
-
Click the project name in Package Explorer and then click Run > Run As > Mule Application.
-
Navigate to the Console view to read the email messages in the logger:
DEBUG: JavaMail version 1.6.3 DEBUG: successfully loaded resource: /META-INF/javamail.default.address.map DEBUG: getProvider() returning javax.mail.Provider[STORE,imap,com.sun.mail.imap.IMAPStore,Oracle] DEBUG IMAP: mail.imap.fetchsize: 16384 DEBUG IMAP: mail.imap.ignorebodystructuresize: false DEBUG IMAP: trying to connect to host "******", port 993, isSSL true * OK The Microsoft Exchange IMAP4 service is ready. [******] A0 CAPABILITY * CAPABILITY IMAP4 IMAP4rev1 AUTH=PLAIN AUTH=XOAUTH2 SASL-IR UIDPLUS MOVE ID UNSELECT CHILDREN IDLE NAMESPACE LITERAL+ A0 OK CAPABILITY completed. ...
If you run the app in Anypoint Studio, the log output prints the debug lines in the console view.
If you run the app in a standalone Mule, the log output prints the debug lines in the log file.
Enable Email Connector Debug Logging
To begin troubleshooting Email Connector, enable debug logging to see the exact error messages:
-
Access Anypoint Studio and navigate to the Package Explorer view.
-
Open your application’s project name.
-
Open the
src/main/resources
path folder. -
Open the
log4j2.xml
file inside the folder. -
If the following line is already in the
log4j2.xml
file, uncomment it to enable it; otherwise, add it:<AsyncLogger name="org.mule.extension.email" level="DEBUG" />
-
Save your changes.
-
Click the project name in Package Explorer and then click Run > Run As > Mule Application.
-
Navigate to the Console view to read the Email Connector’s messages in the logger:
DEBUG 2021-04-26 18:51:08,536 [_pollingSource_imapattachmentFlow/executor.01] [processor: ; event: ] org.mule.extension.email.internal.mailbox.BaseMailboxPollingSource: Poll will be skipped, since last poll emails are still being processed INFO 2021-04-26 18:51:09,166 [[MuleRuntime].uber.04: [imapattachment].imapattachmentFlow.CPU_LITE @111719e0] [processor: imapattachmentFlow/processors/1/processors/2; event: 820f7fe0-a6d9-11eb-a84b-147dda4dba09] org.mule.runtime.core.internal.processor.LoggerMessageProcessor: "" as Binary {base: "64"} DEBUG 2021-04-26 18:51:15,360 [_pollingSource_imapattachmentFlow/executor.01] [processor: ; event: ] org.mule.extension.email.internal.mailbox.BaseMailboxPollingSource: Email [172] was not processed. ....
Troubleshoot Parsing Text File Attachment as Body Message
When Email Connector receives a message without a body and only an attachment file with the Content-Type as text
, the connector publishes the text content as a payload body. To receive the text file in the payload attachments list, set the parsing.text.attachment.as.body
system property to false
. Refer to the set parsing text file attachment as body message documentation for details.
Troubleshoot Jakarta Mail System Properties
Email Connector uses the Java Mail library. Thereby, you can change certain aspects of connector behavior by changing specific Jakarta Mail system properties, such as the MIME type and MIME multipart properties. These properties control conformance to the MIME type specification.
Note that these properties are not session properties and you must set them globally as system properties. To learn how to set system properties in Anypoint Studio or for on-premises deployments, refer to the system properties documentation.
MIME Type System Properties
These are the most used Jakarta Mail MIME type system properties:
-
mail.mime.decodetext.strict
Controls the decoding of MIME-encoded words. The MIME specification requires that encoded-words start at the beginning of a whitespace-separated word. Some mailers incorrectly include encoded-words in the middle of a word. If themail.mime.decodetext.strict
system property is set tofalse
, an attempt is made to decode these illegal encoded-words. Defaults totrue
. -
mail.mime.encodeeol.strict
Controls the choice of Content-Transfer-Encoding for MIME parts that are not of typetext
. Often these MIME parts contain textual data for which an encoding that allows the normal end of line conventions is appropriate. In rare cases, MIME parts that are not of typetext
appear to contain entirely textual data but they require an encoding that preserves CR and LF characters without change. If themail.mime.encodeeol.strict
system property is set totrue
,this type of encoding is used when necessary. Defaults tofalse
. -
mail.mime.charset
Specifies the default MIME charset to use for encoded words and text parts that don’t otherwise the property specify a charset. Usually, the default MIME charset is derived from the default Java charset, as specified in thefile.encoding
system property. Most applications do not need to explicitly set the default MIME charset. Set this property when the default MIME charset to use for mail messages is different than the charset used for files stored on the system. -
mail.mime.ignoreunknownencoding
Controls whether unknown values in the Content-Transfer-Encoding header, as passed to the decode method, cause an exception. If set totrue
, unknown values are ignored and 8bit encoding is assumed. Otherwise, unknown values throw aMessagingException
exception.
MIME Multipart System Properties
These are the most used Jakarta Mail MIME Multipart system properties:
-
mail.mime.multipart.ignoremissingendboundary
Set this property tofalse
to throw aMessagingException
exception if the multipart data does not end with the required end boundary line. If this property is set totrue
or not set at all, missing end boundaries are not considered an error, and the final body part ends at the end of the data. -
mail.mime.multipart.ignoremissingboundaryparameter
+ Set this property tofalse
to throw aMessagingException
exception if the Content-Type of the MIME multipart does not include a boundary parameter. If this property is set totrue
or not set at all, the multipart parsing code searches for a line that looks like a boundary line and uses that line as the boundary separating the parts. -
mail.mime.multipart.ignoreexistingboundaryparameter
Set this property totrue
to ignore any boundary and instead search for a boundary line in the message as with themail.mime.multipart.ignoremissingboundaryparameter
system property. -
mail.mime.multipart.allowempty
Usually, when writing a MIME multipart that contains no body parts, or when trying to parse a multipart message with no body parts, aMessagingException
exception is thrown. The MIME type specification does not allow multipart content with no body parts. Set themail.mime.multipart.allowempty
system property totrue
to override this behavior. When writing out such a MIME multipart, a single empty part is included. When reading such multipart, a MIME multipart is created with no body parts.
Troubleshoot SMTPS and Gmail Connection Issues
The method that you use to troubleshoot SMTPS connection issues depends on whether or not your Gmail account uses two-factor authentication:
Two-Factor Authentication
If your account uses two-factor authentication value, generate an app-specific password and use that instead of your normal password. See Sign in Using App Password for details. You do not need to enable Less Secure Apps in your Gmail account.
Password-Based Authentication
If your Gmail account does not use two-factor authentication, set up and enable Less Secure Apps in your Gmail account, and if your password does not work, go to Allow Access to Your Google Account and follow these steps:
-
Enter your username and password.
-
Enter the letters on the captcha screen.
-
Return to your Mule app and rerun the flow.
Understand the Behavior of the Different Protocols
If your problem is protocol behavior, check the RFC documents. A Request for Comments (RFC) is a publication from the Internet Society (ISOC) and its associated bodies, most prominently the Internet Engineering Task Force (IETF), the principal technical development and standards-setting bodies for the internet. The IETF adopts some of the proposals published as RFCs as internet standards. Some documents that you can check are:
Understand Common Throws
Here is a list of common throw messages and how to interpret them:
-
EMAIL:EMAIL_NOT_FOUND
The email identified by `emailId` cannot be found in a mailbox folder.
-
EMAIL:ACCESSING_FOLDER
There was a problem accessing an email folder or the folder does not exist.
-
EMAIL:CONNECTIVITY
A connection could not be established.
-
EMAIL:RETRY_EXHAUSTED
A problem occurred during message routing.
-
EMAIL:EMAIL_LIST
An error occurred during an attempt to list emails.
-
EMAIL:SEND
An exception occurred during an attempt to send an email.
-
EMAIL:FETCHING_ATTRIBUTES
An error occurred during email attribute parsing from an email.
-
EMAIL:MARK
An error occurred during email flag marking.
-
EMAIL:EXPUNGE_ERROR
A error occurred during an attempt to delete emails from a folder.
-
EMAIL:ATTACHMENT
An error occurred during an attempt to send an attachment.
-
EMAIL:READ_EMAIL
An error occurred during an attempt to read the email content.
-
EMAIL:AUTHENTICATION
Authentication failed.
-
EMAIL:INVALID_CREDENTIALS
An error occurred during the username and password parameter consistency check.
-
EMAIL:UNKNOWN_HOST
The IP address of a host cannot be determined or a port is out of range.
-
EMAIL:CONNECTION_TIMEOUT
The server took too long to reply to a data request.
-
EMAIL:DISCONNECTED
An error occurred during store connecting, or the connection was interrupted.
-
EMAIL:SSL_ERROR
An error occurred during SSL context creation, or the TLS context wasn't properly configured.
-
EMAIL:EMAIL_MOVE
An error occurred during an attempt to move the mail to the target folder.