Contact Us 1-800-596-4880

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:

  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.
    ....

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:

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.
View on GitHub