--- schema_version: "1" id: 85a41bc929fe5a4599f86af4da90c7dbb4dd4d811834952cc72b9eb909a0d459 title: Troubleshooting Email Connector collection: mulesoft version: current locale: en-us portal_url: https://docs.salesforce.com/mulesoft/current/en-us/email-connector/latest/email-troubleshooting.md canonical_url: https://docs.mulesoft.com/email-connector/latest/email-troubleshooting source_site: docs.mulesoft.com content_type: documentation content_hash: 2b229d8d3038c5fc81d9a24715bc18d912dfd13dda635f2f35417b8ca16a1ccd description: MuleSoft Documentation Site release: "1.8" latest: true --- --- product: Email Connector version: 1.8 is-latest-version: true --- # Troubleshooting Email Connector > For the full documentation index, see: https://docs.mulesoft.com/llms.txt 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/.log`. ## Enable JavaMail Debug Logging JavaMail debugging logging is used by underlying third-party classes. To enable JavaMail debugging logging: 1. Access Anypoint Studio and navigate to the **Package Explorer** view. 2. Open your application’s project name. 3. Open the `src/main/mule` path folder. 4. Open your Mule app XML file inside the folder. 5. Add the `` to the IMAP or SMTP connection element. ```xml ``` 6. Save your changes. 7. Click the project name in **Package Explorer** and then click **Run** > **Run As** > **Mule Application**. 8. Navigate to the **Console** view to read the email messages in the logger: ```plain-text 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: 1. Access Anypoint Studio and navigate to the **Package Explorer** view. 2. Open your application’s project name. 3. Open the `src/main/resources` path folder. 4. Open the `log4j2.xml` file inside the folder. 5. If the following line is already in the `log4j2.xml` file, uncomment it to enable it; otherwise, add it: ```xml ``` 6. Save your changes. 7. Click the project name in **Package Explorer** and then click **Run** > **Run As** > **Mule Application**. 8. Navigate to the **Console** view to read the Email Connector’s messages in the logger: ```plain-text 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. .... ``` ### Email Connector Debug Logging for CloudHub 2 Mule Apps Notice that for Mule apps deployed to CloudHub 2, in addition to the SMTP debug setting (``), you must set this property to ensure the SMTP debug logs are captured: `forwardConsoleLogToAnypointMonitoring.enable=true` This is necessary because SMTP debug logging uses the `java.util.logging` API to send logs to the console, which differs from the `log4j2` logging used for other purposes, such as HTTP verbose logging. ## 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](https://docs.mulesoft.com/email-connector/latest/email-attachment) 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](https://docs.mulesoft.com/mule-runtime/latest/mule-app-properties-system) 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 the `mail.mime.decodetext.strict` system property is set to `false`, an attempt is made to decode these illegal encoded-words. Defaults to `true`. - `mail.mime.encodeeol.strict` Controls the choice of Content-Transfer-Encoding for MIME parts that are not of type `text`. 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 type `text` appear to contain entirely textual data but they require an encoding that preserves CR and LF characters without change. If the `mail.mime.encodeeol.strict` system property is set to `true`,this type of encoding is used when necessary. Defaults to `false`. - `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 the `file.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 to `true`, unknown values are ignored and 8bit encoding is assumed. Otherwise, unknown values throw a `MessagingException` exception. ### MIME Multipart System Properties These are the most used Jakarta Mail MIME Multipart system properties: - `mail.mime.multipart.ignoremissingendboundary` Set this property to `false` to throw a `MessagingException` exception if the multipart data does not end with the required end boundary line. If this property is set to `true` 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 to `false` to throw a `MessagingException` exception if the Content-Type of the MIME multipart does not include a boundary parameter. If this property is set to `true` 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 to `true` to ignore any boundary and instead search for a boundary line in the message as with the `mail.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, a `MessagingException` exception is thrown. The MIME type specification does not allow multipart content with no body parts. Set the `mail.mime.multipart.allowempty` system property to `true` 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](https://support.google.com/accounts/answer/185833) 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](https://accounts.google.com/b/0/DisplayUnlockCaptcha) and follow these steps: 1. Enter your username and password. 2. Enter the letters on the captcha screen. 3. 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: - [RFC-5322 - Internet Message Format](https://datatracker.ietf.org/doc/html/rfc5322) - [RFC-1064 - IMAP2 - INTERACTIVE MAIL ACCESS PROTOCOL - VERSION 2](https://datatracker.ietf.org/doc/html/rfc1064) - [RFC-1939 - POP3 - Post Office Protocol - Version 3](https://datatracker.ietf.org/doc/html/rfc1939) - [RFC-5321 - SMTP - Simple Mail Transfer Protocol](https://datatracker.ietf.org/doc/html/rfc5321) - [RFC-2045 - MIME - Multipurpose Internet Mail Extensions Part One: Format of Internet Message Bodies](https://datatracker.ietf.org/doc/html/rfc2045) ## 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. - EMAIL:ILLEGAL\_ARGUMENT An exception occurred while getting the list of emails due to an invalid parameter. ## See Also - [Email Connector Reference](https://docs.mulesoft.com/email-connector/latest/email-documentation) - [Salesforce Help](https://help.salesforce.com) - [Known Issues](https://help.salesforce.com/s/issues)