Troubleshooting Email Connector | MuleSoft Documentation
# Troubleshooting Email Connector
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:
  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 `<property key="mail.debug" value="true"/>` to the IMAP or SMTP connection element.
```
 <email:imaps-connection host="..." user="..." password="..." >
  <email:properties >
   <email:property key="mail.debug" value="true" />
  </email:properties>
 </email:imaps-connection>
```

  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:
```
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:
```
<AsyncLogger name="org.mule.extension.email" level="DEBUG" />
```

  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:
```
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 (`<email:property key="mail.debug" value="true" />`), 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 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 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 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:
  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
  * RFC-1064 - IMAP2 - INTERACTIVE MAIL ACCESS PROTOCOL - VERSION 2
  * RFC-1939 - POP3 - Post Office Protocol - Version 3
  * RFC-5321 - SMTP - Simple Mail Transfer Protocol
  * RFC-2045 - MIME - Multipurpose Internet Mail Extensions Part One: Format of Internet Message Bodies


## 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
  * MuleSoft Help Center
  *