Package com.chilkatsoft.chilkat2

Class Imap

java.lang.Object
com.chilkatsoft.chilkat2.ChilkatObject
com.chilkatsoft.chilkat2.Imap
All Implemented Interfaces:
AutoCloseable
public class Imap extends ChilkatObject
<section class="imap-summary">

Access, search, download, organize, and monitor email on IMAP servers.

Chilkat.Imap is a full-featured IMAP client class for applications that need reliable server-side email access and mailbox management. It supports secure connections, authentication, mailbox selection, message searching, downloading email and attachments, flag management, moving and copying messages, appending MIME, IDLE-based change monitoring, and detailed diagnostics for troubleshooting server behavior.

Secure IMAP connections

Connect with SSL/TLS, STARTTLS, OAuth2, password authentication, proxy settings, timeouts, and connection diagnostics.

Mailbox selection and listing

List mailboxes, select folders, inspect mailbox state, and work with server-side folders such as Inbox, Sent, Archive, or custom folders.

Search and fetch messages

Search by IMAP criteria, work with UIDs or sequence numbers, download full messages, headers, MIME, body text, or selected message parts.

Message management

Set and clear flags, mark messages read or unread, copy or move messages, delete messages, expunge mailboxes, and append MIME to folders.

Attachments and MIME

Retrieve email as Chilkat Email objects, process MIME content, and save or inspect attachments as needed.

IDLE and diagnostics

Monitor mailbox changes with IMAP IDLE and use detailed logging, response text, and LastErrorText to troubleshoot servers.

Common pattern: Connect securely, authenticate, select a mailbox, search or fetch messages using UIDs when possible, perform message or folder operations, then disconnect cleanly. Use detailed diagnostics when working with provider- specific IMAP behavior.

For an extended overview, see Imap Class Overview.

</section>

Event-capable: long-running methods report progress through a ProgressListener installed with setProgressListener(ProgressListener), onAbortCheck(BooleanSupplier), onPercentDone(IntPredicate) or onProgressInfo(BiConsumer).

Instances hold a native Chilkat object: close them with ChilkatObject.close() (try-with-resources) when done; an unclosed instance is freed when it becomes unreachable.

See Also:
Online reference

  • Constructor Details

    • Imap

      public Imap()
      Creates a new Imap object.

  • Method Details

    • getAbortCurrent

      public boolean getAbortCurrent()
      Controls cancellation of the method currently running on this Imap object.
      • Set this property to true to request that a long-running network operation abort.
      • Short methods that do not perform lengthy processing or network communication are generally unaffected.
      • Both synchronous and asynchronous calls can be aborted. A synchronous call may be canceled by setting this property from another thread.

      The property is automatically reset to false when the abort is processed. If no method is running, it is reset when the next method begins.

      Canceling an operation can leave the connection in an uncertain state. Close the connection, reconnect, authenticate again, and reselect the mailbox before continuing. Output objects may contain partial results, and a server-side operation may already have been partially applied before cancellation.

      Returns:
      the value of the AbortCurrent property

    • setAbortCurrent

      public void setAbortCurrent​(boolean value)
      Sets the AbortCurrent property; see getAbortCurrent().
      Parameters:
      value - the new value

    • getAppendSeen

      public boolean getAppendSeen()
      Controls the initial \Seen flag for these methods:
      • true (the default): the appended message is marked as seen.
      • false: the appended message is initially unseen.

      The flag-specific append methods use their explicit arguments and do not use this property.

      Returns:
      the value of the AppendSeen property

    • setAppendSeen

      public void setAppendSeen​(boolean value)
      Sets the AppendSeen property; see getAppendSeen().
      Parameters:
      value - the new value

    • getAppendUid

      public int getAppendUid()
      Contains the UID assigned by the server to the message most recently appended successfully.

      The default is 0. After any successful append, this property is set to the UID reported by the server, or to 0 if the server succeeds but does not report an appended UID. A failed append leaves the previous value unchanged.

      Returns:
      the value of the AppendUid property (read-only)

    • getAuthMethod

      public String getAuthMethod()
      Selects the IMAP authentication mechanism. Matching is case-insensitive, but spelling matters.

      Value Purpose

      LOGIN Username and password authentication.

      PLAIN SASL PLAIN authentication. getAuthzId() may also be used.

      CRAM-MD5 Challenge-response authentication when supported by the server.

      NTLM Windows Integrated Authentication.

      XOAUTH2 OAuth 2.0 access-token authentication.

      The default is LOGIN, and an empty or unrecognized value also uses the LOGIN method. If the selected mechanism fails or is not supported by the server, Chilkat does not fall back to another authentication method.

      If NTLM authentication fails because of an NTLM-version compatibility issue, set Global.DefaultNtlmVersion to 1 and retry.

      Returns:
      the value of the AuthMethod property

    • setAuthMethod

      public void setAuthMethod​(String value)
      Sets the AuthMethod property; see getAuthMethod().
      Parameters:
      value - the new value (not null)

    • getAuthzId

      public String getAuthzId()
      Specifies the optional authorization identity used with the PLAIN authentication mechanism.

      Leave this property empty unless the IMAP server requires an authorization identity that differs from the login identity supplied to login(String, String).

      Returns:
      the value of the AuthzId property

    • setAuthzId

      public void setAuthzId​(String value)
      Sets the AuthzId property; see getAuthzId().
      Parameters:
      value - the new value (not null)

    • getAutoDownloadAttachments

      public boolean getAutoDownloadAttachments()
      Controls whether methods that download a complete email also download ordinary attachment bodies. The default is true.
      • true: complete-email fetches include attachment bodies.
      • false: complete-email fetches omit ordinary attachment bodies, whether the result is returned as an Email object or as MIME.

      Header-only methods never download attachment bodies. They add ckx-imap-* metadata describing the attachments, which can be read with getMailNumAttach(Email), getMailAttachFilename(Email, int), and getMailAttachSize(Email, int). In this state, the Email object's ordinary attachment count can still be 0.

      Related MIME parts used by an HTML body are not treated as ordinary attachments. Signed or encrypted messages are always downloaded in full because their complete MIME is required for verification or decryption.

      Returns:
      the value of the AutoDownloadAttachments property

    • setAutoDownloadAttachments

      public void setAutoDownloadAttachments​(boolean value)
      Sets the AutoDownloadAttachments property; see getAutoDownloadAttachments().
      Parameters:
      value - the new value

    • getAutoFix

      public boolean getAutoFix()
      When true (the default), changes the public getSsl() and getStartTls() property values when connect(String) is called for a standard IMAP port:
      • Port 993: sets Ssl to true and StartTls to false for implicit TLS.
      • Port 143: sets Ssl to false. The existing StartTls value determines whether the connection is upgraded explicitly.

      For a nonstandard port, this property makes no changes. Set it to false when the application must preserve an unusual port and TLS combination exactly as configured.

      Returns:
      the value of the AutoFix property

    • setAutoFix

      public void setAutoFix​(boolean value)
      Sets the AutoFix property; see getAutoFix().
      Parameters:
      value - the new value

    • getClientIpAddress

      public String getClientIpAddress()
      Specifies the local IP address to bind when the computer has multiple network interfaces or addresses.

      Leave this property empty for the usual case. The operating system will select the default local interface. When set, use a numeric IP address such as 165.164.55.124, not a hostname.

      Returns:
      the value of the ClientIpAddress property

    • setClientIpAddress

      public void setClientIpAddress​(String value)
      Sets the ClientIpAddress property; see getClientIpAddress().
      Parameters:
      value - the new value (not null)

    • getConnectTimeout

      public int getConnectTimeout()
      The maximum number of seconds to wait while establishing the TCP connection to the IMAP server.

      The default is 30 seconds. This timeout applies to connection establishment, not to later reads from the server.

      Returns:
      the value of the ConnectTimeout property

    • setConnectTimeout

      public void setConnectTimeout​(int value)
      Sets the ConnectTimeout property; see getConnectTimeout().
      Parameters:
      value - the new value

    • getConnectedToHost

      public String getConnectedToHost()
      Contains the hostname or IP address of the IMAP server to which the object is currently connected.

      Returns an empty string when no connection is active.

      Returns:
      the value of the ConnectedToHost property (read-only)

    • getDomain

      public String getDomain()
      Specifies the Windows domain used for NTLM authentication.

      This property is optional and may be left empty when the login name already identifies the domain or when NTLM is not used.

      Returns:
      the value of the Domain property

    • setDomain

      public void setDomain​(String value)
      Sets the Domain property; see getDomain().
      Parameters:
      value - the new value (not null)

    • getEnableSecrets

      public boolean getEnableSecrets()
      Enables automatic resolution of credential values from secure operating-system storage. The default is false.

      When true, supported password arguments and properties may contain a secret specification beginning with !! instead of a literal secret. Chilkat resolves the value from Windows Credential Manager or Apple Keychain. 

      !![appName|]service[|domain]|username

      This applies to getHttpProxyPassword(), getSocksPassword(), the password supplied to login(String, String), and the password supplied to sshAuthenticatePw(String, String).

      Returns:
      the value of the EnableSecrets property

    • setEnableSecrets

      public void setEnableSecrets​(boolean value)
      Sets the EnableSecrets property; see getEnableSecrets().
      Parameters:
      value - the new value

    • getHeartbeatMs

      public int getHeartbeatMs()
      Sets the interval, in milliseconds, between AbortCheck event callbacks during operations that support cancellation.

      The default is 0, which disables periodic AbortCheck callbacks.

      Returns:
      the value of the HeartbeatMs property

    • setHeartbeatMs

      public void setHeartbeatMs​(int value)
      Sets the HeartbeatMs property; see getHeartbeatMs().
      Parameters:
      value - the new value

    • getHighestModSeq

      public String getHighestModSeq()
      Contains the HIGHESTMODSEQ value of the currently selected mailbox as a decimal string.

      The value is 0 when no mailbox is selected or the server does not provide this information. A string is used because the value may exceed the integer range of some programming languages.

      Returns:
      the value of the HighestModSeq property (read-only)

    • getHttpProxyAuthMethod

      public String getHttpProxyAuthMethod()
      Specifies the authentication mechanism used by an HTTP proxy.

      Valid values are Basic and NTLM. This property is used only when getHttpProxyHostname() identifies an HTTP proxy that requires authentication.

      Returns:
      the value of the HttpProxyAuthMethod property

    • setHttpProxyAuthMethod

      public void setHttpProxyAuthMethod​(String value)
      Sets the HttpProxyAuthMethod property; see getHttpProxyAuthMethod().
      Parameters:
      value - the new value (not null)

    • getHttpProxyDomain

      public String getHttpProxyDomain()
      Specifies the optional Windows domain for HTTP-proxy NTLM authentication.

      It is ignored when the proxy does not use NTLM authentication.

      Returns:
      the value of the HttpProxyDomain property

    • setHttpProxyDomain

      public void setHttpProxyDomain​(String value)
      Sets the HttpProxyDomain property; see getHttpProxyDomain().
      Parameters:
      value - the new value (not null)

    • getHttpProxyHostname

      public String getHttpProxyHostname()
      Specifies the hostname or numeric IPv4 address of an HTTP proxy through which the IMAP connection is established.

      Leave this property empty to connect directly or to use another configured transport such as SOCKS or SSH tunneling.

      Returns:
      the value of the HttpProxyHostname property

    • setHttpProxyHostname

      public void setHttpProxyHostname​(String value)
      Sets the HttpProxyHostname property; see getHttpProxyHostname().
      Parameters:
      value - the new value (not null)

    • getHttpProxyPassword

      public String getHttpProxyPassword()
      Specifies the password used to authenticate with the configured HTTP proxy.

      It is used only when the proxy requires authentication.

      Returns:
      the value of the HttpProxyPassword property

    • setHttpProxyPassword

      public void setHttpProxyPassword​(String value)
      Sets the HttpProxyPassword property; see getHttpProxyPassword().
      Parameters:
      value - the new value (not null)

    • getHttpProxyPort

      public int getHttpProxyPort()
      Specifies the TCP port of the configured HTTP proxy.

      Common values include 8080 and 3128, but the correct value is determined by the proxy server configuration.

      Returns:
      the value of the HttpProxyPort property

    • setHttpProxyPort

      public void setHttpProxyPort​(int value)
      Sets the HttpProxyPort property; see getHttpProxyPort().
      Parameters:
      value - the new value

    • getHttpProxyUsername

      public String getHttpProxyUsername()
      Specifies the username used to authenticate with the configured HTTP proxy.

      It is used only when the proxy requires authentication.

      Returns:
      the value of the HttpProxyUsername property

    • setHttpProxyUsername

      public void setHttpProxyUsername​(String value)
      Sets the HttpProxyUsername property; see getHttpProxyUsername().
      Parameters:
      value - the new value (not null)

    • getKeepSessionLog

      public boolean getKeepSessionLog()
      Enables or disables the in-memory IMAP protocol log. The default is false.

      When enabled, getSessionLog() contains the raw commands sent to the server and the raw responses received. Use clearSessionLog() to reset it.

      Returns:
      the value of the KeepSessionLog property

    • setKeepSessionLog

      public void setKeepSessionLog​(boolean value)
      Sets the KeepSessionLog property; see getKeepSessionLog().
      Parameters:
      value - the new value

    • getLastAppendedMime

      public String getLastAppendedMime()
      Contains the MIME source sent by the most recent successful call to one of the following methods:

      A failed append leaves the previous value unchanged. Therefore, read this property only after confirming that the append method succeeded.

      Returns:
      the value of the LastAppendedMime property (read-only)

    • getLastCommand

      public String getLastCommand()
      Contains the most recent raw IMAP command sent to the server.

      This property is primarily intended for diagnostics when an IMAP operation fails or produces an unexpected response.

      Returns:
      the value of the LastCommand property (read-only)

    • getLastIntermediateResponse

      public String getLastIntermediateResponse()
      Contains the most recent intermediate response received from the IMAP server while a command was in progress.

      Use it for protocol-level diagnostics when a command involves continuations or multiple response stages.

      Returns:
      the value of the LastIntermediateResponse property (read-only)

    • getLastResponse

      public String getLastResponse()
      Contains the raw response most recently received from the IMAP server.

      This property is cleared when Chilkat sends a new command. If a method fails during local argument validation or before a command is sent, the previous response can remain here. Also, a method can return failure even when the last tagged server response is OK, such as when a syntactically successful FETCH returns no matching message. Use the method return value or LastMethodSuccess as the authoritative success indicator.

      Returns:
      the value of the LastResponse property (read-only)

    • getLastResponseCode

      public String getLastResponseCode()
      Contains the optional IMAP response code from the most recent server response, such as NONEXISTENT or AUTHENTICATIONFAILED. Response-code strings vary by server.

      If a method fails before sending an IMAP command, this property can still contain the response code from an earlier command. Use the method return value or LastMethodSuccess to determine whether the current operation succeeded.

      Returns:
      the value of the LastResponseCode property (read-only)

    • getLoggedInUser

      public String getLoggedInUser()
      Contains the username of the authenticated IMAP session.

      Returns an empty string when the object is not logged in.

      Returns:
      the value of the LoggedInUser property (read-only)

    • getNumMessages

      public int getNumMessages()
      Contains the number of messages reported when the current mailbox was selected.

      The value is updated by selectMailbox(String) and examineMailbox(String). Unsolicited EXISTS notifications returned by idleCheck(int) do not automatically update this property; use the notification value or reselect/query the mailbox when a refreshed count is needed.

      Returns:
      the value of the NumMessages property (read-only)

    • getPeekMode

      public boolean getPeekMode()
      Controls whether fetching full message content marks the message as seen.
      • false (the default): fetching a full message or its raw MIME may set the \Seen flag.
      • true: full message data and raw MIME are fetched without setting \Seen, using IMAP peek semantics.

      Fetching headers only does not set \Seen, regardless of this property.

      Returns:
      the value of the PeekMode property

    • setPeekMode

      public void setPeekMode​(boolean value)
      Sets the PeekMode property; see getPeekMode().
      Parameters:
      value - the new value

    • getPercentDoneScale

      public int getPercentDoneScale()
      Sets the scale used by PercentDone event callbacks. The default is 100.

      For example, a scale of 1000 gives tenths-of-a-percent precision, so a callback value of 453 represents 45.3% complete. Values are limited to the range 10 through 100000.

      This property applies only to languages and environments that support event callbacks and only to operations for which progress can be measured.

      Returns:
      the value of the PercentDoneScale property

    • setPercentDoneScale

      public void setPercentDoneScale​(int value)
      Sets the PercentDoneScale property; see getPercentDoneScale().
      Parameters:
      value - the new value

    • getPort

      public int getPort()
      Specifies the IMAP server port. The default is 143.
      • 993 is the standard port for implicit TLS and is normally used with getSsl() set to true.
      • 143 is the standard port for ordinary IMAP and for explicit TLS requested with getStartTls().

      When getAutoFix() is enabled, standard port values are used to adjust the effective TLS configuration when connecting.

      Returns:
      the value of the Port property

    • setPort

      public void setPort​(int value)
      Sets the Port property; see getPort().
      Parameters:
      value - the new value

    • getPreferIpv6

      public boolean getPreferIpv6()
      Controls address-family preference when a hostname resolves to both IPv4 and IPv6 addresses.
      • false (the default): prefer IPv4.
      • true: prefer IPv6.

      The other address family may still be used when the preferred one is unavailable.

      Returns:
      the value of the PreferIpv6 property

    • setPreferIpv6

      public void setPreferIpv6​(boolean value)
      Sets the PreferIpv6 property; see getPreferIpv6().
      Parameters:
      value - the new value

    • getReadTimeout

      public int getReadTimeout()
      The maximum number of seconds that an incoming IMAP response may stall with no additional bytes received.

      The default is 60 seconds. This is an inactivity timeout, not a limit on the total time allowed for a large response.

      Returns:
      the value of the ReadTimeout property

    • setReadTimeout

      public void setReadTimeout​(int value)
      Sets the ReadTimeout property; see getReadTimeout().
      Parameters:
      value - the new value

    • getRequireSslCertVerify

      public boolean getRequireSslCertVerify()
      Controls verification of the IMAP server's TLS certificate chain.
      • false (the default): a connection is not rejected solely because normal certificate-chain verification fails.
      • true: the connection fails when the certificate is expired, is not yet valid, its signature is invalid, or its chain cannot be verified to a trusted root.

      Certificate-chain verification is separate from hostname matching and public-key pinning. Hostname matching, when required, is enforced independently even when this property is false. getTlsPinSet() supplements rather than replaces normal certificate verification.

      The hostname used for the TLS connection is also used for Server Name Indication (SNI) and certificate hostname comparison.

      Returns:
      the value of the RequireSslCertVerify property

    • setRequireSslCertVerify

      public void setRequireSslCertVerify​(boolean value)
      Sets the RequireSslCertVerify property; see getRequireSslCertVerify().
      Parameters:
      value - the new value

    • getSearchCharset

      public String getSearchCharset()
      Specifies the IMAP CHARSET used by Search, queryMbx(String, boolean, MessageSet), and queryThread(String, String, boolean, JsonObject) when search criteria contain non-ASCII characters. The default is UTF-8.

      If the criteria contain only 7-bit ASCII characters, no CHARSET is needed and this property has no effect. The value AUTO enables the legacy behavior of selecting a charset by examining the criteria text.

      Most applications should leave this property unchanged unless a particular server rejects non-English search text.

      Returns:
      the value of the SearchCharset property

    • setSearchCharset

      public void setSearchCharset​(String value)
      Sets the SearchCharset property; see getSearchCharset().
      Parameters:
      value - the new value (not null)

    • getSelectedMailbox

      public String getSelectedMailbox()
      Contains the name of the currently selected or examined mailbox.

      Returns an empty string when no mailbox is selected.

      Returns:
      the value of the SelectedMailbox property (read-only)

    • getSendBufferSize

      public int getSendBufferSize()
      Specifies the application-level buffer size used when sending data through the underlying TCP connection.

      The default is 32767 bytes. Most applications should leave this setting unchanged.

      Returns:
      the value of the SendBufferSize property

    • setSendBufferSize

      public void setSendBufferSize​(int value)
      Sets the SendBufferSize property; see getSendBufferSize().
      Parameters:
      value - the new value

    • getSeparatorChar

      public String getSeparatorChar()
      Contains the mailbox-hierarchy delimiter reported by the IMAP server, typically / or ..

      mbxList(boolean, String, String, Mailboxes) and the legacy mailbox-listing methods update this property from the server's LIST response. The value is a string containing one character.

      Returns:
      the value of the SeparatorChar property

    • setSeparatorChar

      public void setSeparatorChar​(String value)
      Sets the SeparatorChar property; see getSeparatorChar().
      Parameters:
      value - the new value (not null)

    • getSessionLog

      public String getSessionLog()
      Contains the in-memory log of raw IMAP commands and server responses.

      getKeepSessionLog() must be true for logging to occur. Call clearSessionLog() to remove previously collected entries.

      Chilkat redacts sensitive credentials, including passwords and OAuth access tokens, from session logs, diagnostic logs, and LastErrorText.

      Returns:
      the value of the SessionLog property (read-only)

    • getSoRcvBuf

      public int getSoRcvBuf()
      Sets the operating system's TCP receive-buffer size. The default is 4194304 bytes.

      Most applications should leave this unchanged. Increasing it may improve download throughput on high-latency or high-bandwidth networks. Values that are multiples of 4096 are recommended.

      Returns:
      the value of the SoRcvBuf property

    • setSoRcvBuf

      public void setSoRcvBuf​(int value)
      Sets the SoRcvBuf property; see getSoRcvBuf().
      Parameters:
      value - the new value

    • getSoSndBuf

      public int getSoSndBuf()
      Sets the operating system's TCP send-buffer size. The default is 262144 bytes.

      Most applications should leave this unchanged. Increasing it may improve upload throughput; values such as 524288 or 1048576 may be tested when needed.

      Returns:
      the value of the SoSndBuf property

    • setSoSndBuf

      public void setSoSndBuf​(int value)
      Sets the SoSndBuf property; see getSoSndBuf().
      Parameters:
      value - the new value

    • getSocksHostname

      public String getSocksHostname()
      Specifies the hostname or numeric IP address of the SOCKS proxy.

      This property is used only when getSocksVersion() is 4 or 5.

      Returns:
      the value of the SocksHostname property

    • setSocksHostname

      public void setSocksHostname​(String value)
      Sets the SocksHostname property; see getSocksHostname().
      Parameters:
      value - the new value (not null)

    • getSocksPassword

      public String getSocksPassword()
      Specifies the SOCKS5 proxy password.

      It is ignored for SOCKS4 because SOCKS4 does not define password authentication.

      Returns:
      the value of the SocksPassword property

    • setSocksPassword

      public void setSocksPassword​(String value)
      Sets the SocksPassword property; see getSocksPassword().
      Parameters:
      value - the new value (not null)

    • getSocksPort

      public int getSocksPort()
      Specifies the SOCKS proxy port. The default is 1080.

      This property is used only when getSocksVersion() is 4 or 5.

      Returns:
      the value of the SocksPort property

    • setSocksPort

      public void setSocksPort​(int value)
      Sets the SocksPort property; see getSocksPort().
      Parameters:
      value - the new value

    • getSocksUsername

      public String getSocksUsername()
      Specifies the username sent to a SOCKS4 or SOCKS5 proxy.

      This property is used only when getSocksVersion() is 4 or 5.

      Returns:
      the value of the SocksUsername property

    • setSocksUsername

      public void setSocksUsername​(String value)
      Sets the SocksUsername property; see getSocksUsername().
      Parameters:
      value - the new value (not null)

    • getSocksVersion

      public int getSocksVersion()
      Selects whether the IMAP connection uses a SOCKS proxy.

      Value Behavior

      0 Do not use a SOCKS proxy. This is the default.

      4 Connect through a SOCKS4 proxy.

      5 Connect through a SOCKS5 proxy.

      Returns:
      the value of the SocksVersion property

    • setSocksVersion

      public void setSocksVersion​(int value)
      Sets the SocksVersion property; see getSocksVersion().
      Parameters:
      value - the new value

    • getSortCriteria

      public String getSortCriteria()
      Specifies the sort order used by queryMbx(String, boolean, MessageSet). The default is the empty string, which uses an ordinary IMAP SEARCH.

      Set this property to a space-separated list of sort keys. Sorting is ascending unless REVERSE precedes a key. Supported keys are ARRIVAL, CC, DATE, FROM, SIZE, SUBJECT, and TO.

      Examples:

      • SUBJECT REVERSE DATE
      • REVERSE SIZE
      • ARRIVAL

      If the server does not support the IMAP SORT extension, Chilkat automatically falls back to an ordinary SEARCH.

      Returns:
      the value of the SortCriteria property

    • setSortCriteria

      public void setSortCriteria​(String value)
      Sets the SortCriteria property; see getSortCriteria().
      Parameters:
      value - the new value (not null)

    • getSsl

      public boolean getSsl()
      Controls implicit TLS for the IMAP connection. The default is false.
      • true: begin the connection with a TLS handshake, typically on port 993.
      • false: begin with ordinary IMAP. Use getStartTls() when the server requires an explicit STARTTLS upgrade.

      If both this property and getStartTls() are true, implicit TLS takes precedence and STARTTLS is not used.

      Returns:
      the value of the Ssl property

    • setSsl

      public void setSsl​(boolean value)
      Sets the Ssl property; see getSsl().
      Parameters:
      value - the new value

    • getSslAllowedCiphers

      public String getSslAllowedCiphers()
      Restricts the cipher suites and selected TLS security requirements offered for an IMAP TLS connection.

      Leave this property empty to allow all cipher suites implemented by the installed Chilkat version. To restrict negotiation, provide a comma-separated list in preference order, for example: 

      TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384, TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

      The server chooses from the cipher suites offered by the client; the client cannot force a suite the server does not support.

      The list may also contain these policy keywords:

      • rsa1024 or rsa2048 to require a minimum RSA server-key size.
      • secure-renegotiation to require secure TLS renegotiation.
      • best-practices to use the security policy recommended by the installed Chilkat version.

      Legacy keywords such as aes256-cbc, aes128-cbc, 3des-cbc, and rc4 remain recognized for compatibility, but explicitly listing acceptable suites is preferred.

      Returns:
      the value of the SslAllowedCiphers property

    • setSslAllowedCiphers

      public void setSslAllowedCiphers​(String value)
      Sets the SslAllowedCiphers property; see getSslAllowedCiphers().
      Parameters:
      value - the new value (not null)

    • getSslProtocol

      public String getSslProtocol()
      Selects the TLS protocol version or minimum version allowed for secure IMAP connections.

      The complete list of accepted values is:

      • default
      • TLS 1.3
      • TLS 1.2
      • TLS 1.1
      • TLS 1.0
      • SSL 3.0
      • TLS 1.3 or higher
      • TLS 1.2 or higher
      • TLS 1.1 or higher
      • TLS 1.0 or higher

      The default is default, which allows Chilkat to negotiate a protocol supported by both client and server. A minimum-version setting is generally more interoperable than requiring one exact version.

      Returns:
      the value of the SslProtocol property

    • setSslProtocol

      public void setSslProtocol​(String value)
      Sets the SslProtocol property; see getSslProtocol().
      Parameters:
      value - the new value (not null)

    • getSslServerCertVerified

      public boolean getSslServerCertVerified()
      Indicates whether the IMAP server certificate chain was successfully verified for the current or most recent TLS connection.

      This property reports certificate-chain verification only. It does not report hostname matching or public-key pinning. If hostname matching or pinning is required and the check fails, the connection itself fails.

      Returns:
      the value of the SslServerCertVerified property (read-only)

    • getStartTls

      public boolean getStartTls()
      Controls explicit TLS using the IMAP STARTTLS command. The default is false.
      • true: connect in clear text, issue STARTTLS, and then continue through an encrypted channel.
      • false: do not request an explicit TLS upgrade.

      Explicit TLS is commonly used on port 143. For implicit TLS, set getSsl() to true and normally use port 993. If both properties are true, getSsl() takes precedence.

      Returns:
      the value of the StartTls property

    • setStartTls

      public void setStartTls​(boolean value)
      Sets the StartTls property; see getStartTls().
      Parameters:
      value - the new value

    • getTlsCipherSuite

      public String getTlsCipherSuite()
      Contains the cipher suite negotiated for the current or most recent TLS connection, for example TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384.

      The value is empty before a TLS connection has been established or after a failed TLS negotiation.

      Returns:
      the value of the TlsCipherSuite property (read-only)

    • getTlsPinSet

      public String getTlsPinSet()
      Specifies one or more expected SPKI fingerprints for TLS public-key pinning. If none of the configured pins matches the server certificate, the TLS handshake fails.

      Pinning supplements normal certificate-chain verification; it does not replace it. A matching pin does not make an expired or otherwise invalid certificate acceptable. When a pin set is configured, pin matching is enforced even if getRequireSslCertVerify() is false.

      The format is: 

      hashAlgorithm, encoding, fingerprint1, fingerprint2, ...

      Example: 

      sha256, base64, lKg1SIqyhPSK19tlPbjl8s02yChsVTDklQpkMCHvsTE=

      Supported hash algorithms include sha1, sha256, sha384, sha512, md2, md5, haval, ripemd128, ripemd160, ripemd256, and ripemd320. Supported encodings include base64, hex, and other Chilkat-supported binary encodings.

      Returns:
      the value of the TlsPinSet property

    • setTlsPinSet

      public void setTlsPinSet​(String value)
      Sets the TlsPinSet property; see getTlsPinSet().
      Parameters:
      value - the new value (not null)

    • getTlsVersion

      public String getTlsVersion()
      Contains the protocol version negotiated for the current or most recent TLS connection, such as TLS 1.2 or TLS 1.3.

      The value is empty before a TLS connection has been established or after a failed TLS negotiation.

      Returns:
      the value of the TlsVersion property (read-only)

    • getUidNext

      public long getUidNext()
      Contains the mailbox's reported UIDNEXT value—the UID expected to be assigned to the next appended message.

      The value is 0 when no mailbox is selected or when the server did not provide UIDNEXT.

      Returns:
      the value of the UidNext property (read-only)

    • getUidValidity

      public long getUidValidity()
      Contains the UIDVALIDITY value of the currently selected mailbox, or 0 when no mailbox is selected.

      An application that stores message UIDs should also store this value. If UIDVALIDITY changes in a later session, previously stored UIDs must no longer be assumed to identify the same messages.

      Returns:
      the value of the UidValidity property (read-only)

    • getUncommonOptions

      public String getUncommonOptions()
      Provides comma-separated compatibility or platform-specific options for uncommon cases. The default is an empty string, and most applications should leave it unchanged.
      • ProtectFromVpn: on Android, bypasses an installed or active VPN.
      • EnableTls13: legacy option that enabled offering TLS 1.3 in versions where it was not yet enabled by default.

      Returns:
      the value of the UncommonOptions property

    • setUncommonOptions

      public void setUncommonOptions​(String value)
      Sets the UncommonOptions property; see getUncommonOptions().
      Parameters:
      value - the new value (not null)

    • addPfxSourceBd

      public void addPfxSourceBd​(BinData bd, String password)
      Adds the PKCS #12/PFX data in the BinData in bd as a source of certificates and private keys for S/MIME processing.

      password contains the PFX password. Call this method once for each additional source.

      Parameters:
      bd - the bd argument (not null)
      password - the password argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • addPfxSourceFile

      public void addPfxSourceFile​(String pfxFilePath, String pfxPassword)
      Adds a PKCS #12/PFX file that may be searched for certificates and private keys needed for S/MIME decryption or signature processing.

      pfxFilePath is the local filesystem path of the PFX file, and pfxPassword contains its password. Call this method once for each additional source.

      On Windows, system certificate stores are also searched automatically. On macOS, the Keychain is searched automatically.

      Parameters:
      pfxFilePath - the pfxFilePath argument (not null)
      pfxPassword - the pfxPassword argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • appendMail

      public void appendMail​(String mailbox, Email email)
      Appends the Email in email to the mailbox named by mailbox.

      getAppendSeen() controls the initial \Seen flag. After success, getAppendUid() contains the UID reported by the server, or 0 if no UID was reported, and getLastAppendedMime() contains the MIME sent.

      Rendering for the append does not generate or replace email's Date, Message-ID, or MIME boundary values. If email uses an 8bit or binary transfer encoding that would produce non-text binary bytes, Chilkat changes the rendered transfer encoding to a text-safe encoding such as Base64.

      Mailbox names may be supplied as normal Unicode strings. Chilkat automatically handles IMAP modified UTF-7 or UTF-8 mailbox-name encoding as required by the server.

      Parameters:
      mailbox - the mailbox argument (not null)
      email - the email argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • appendMime

      public void appendMime​(String mailbox, String mimeText)
      Appends the complete RFC 822/MIME message in mimeText to the mailbox named by mailbox.

      getAppendSeen() controls the initial \Seen flag. After success, getAppendUid() contains the UID reported by the server, or 0 if no UID was reported, and getLastAppendedMime() contains the MIME sent.

      The MIME text is sent exactly as supplied. Chilkat does not normalize line endings, add a final CRLF, or re-encode headers or body content. The supplied text must not contain non-text binary bytes.

      Mailbox names may be supplied as normal Unicode strings. Chilkat automatically handles IMAP modified UTF-7 or UTF-8 mailbox-name encoding as required by the server.

      Parameters:
      mailbox - the mailbox argument (not null)
      mimeText - the mimeText argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • appendMimeWithDateStr

      public void appendMimeWithDateStr​(String mailbox, String mimeText, String internalDateStr)
      Appends the MIME message in mimeText to the mailbox named by mailbox while explicitly setting the server-side internal date from internalDateStr.

      internalDateStr is an RFC 822 date/time string, for example Fri, 10 Jul 2026 20:15:30 GMT. The internal date is mailbox metadata and is distinct from the message's Date header. getAppendSeen() controls the initial \Seen flag.

      The MIME text is sent exactly as supplied. Chilkat does not normalize line endings, add a final CRLF, or re-encode headers or body content. The supplied text must not contain non-text binary bytes.

      Mailbox names may be supplied as normal Unicode strings. Chilkat automatically handles IMAP modified UTF-7 or UTF-8 mailbox-name encoding as required by the server.

      Parameters:
      mailbox - the mailbox argument (not null)
      mimeText - the mimeText argument (not null)
      internalDateStr - the internalDateStr argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • appendMimeWithFlags

      public void appendMimeWithFlags​(String mailbox, String mimeText, boolean seen, boolean flagged, boolean answered, boolean draft)
      Appends the MIME message in mimeText to the mailbox named by mailbox and sets its initial system flags.
      • seen controls \Seen.
      • flagged controls \Flagged.
      • answered controls \Answered.
      • draft controls \Draft.

      Use true to set a flag and false to leave it unset. The explicit flag arguments are used instead of getAppendSeen().

      The MIME text is sent exactly as supplied. Chilkat does not normalize line endings, add a final CRLF, or re-encode headers or body content. The supplied text must not contain non-text binary bytes.

      Mailbox names may be supplied as normal Unicode strings. Chilkat automatically handles IMAP modified UTF-7 or UTF-8 mailbox-name encoding as required by the server.

      Parameters:
      mailbox - the mailbox argument (not null)
      mimeText - the mimeText argument (not null)
      seen - the seen argument
      flagged - the flagged argument
      answered - the answered argument
      draft - the draft argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • appendMimeWithFlagsSb

      public void appendMimeWithFlagsSb​(String mailbox, StringBuilder sbMime, boolean seen, boolean flagged, boolean answered, boolean draft)
      Appends the MIME contained in the StringBuilder in sbMime to mailbox mailbox and sets its initial system flags.
      • seen controls \Seen.
      • flagged controls \Flagged.
      • answered controls \Answered.
      • draft controls \Draft.

      The explicit flag arguments are used instead of getAppendSeen().

      The MIME text is sent exactly as supplied. Chilkat does not normalize line endings, add a final CRLF, or re-encode headers or body content. The supplied text must not contain non-text binary bytes.

      Mailbox names may be supplied as normal Unicode strings. Chilkat automatically handles IMAP modified UTF-7 or UTF-8 mailbox-name encoding as required by the server.

      Parameters:
      mailbox - the mailbox argument (not null)
      sbMime - the sbMime argument (not null)
      seen - the seen argument
      flagged - the flagged argument
      answered - the answered argument
      draft - the draft argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • capability

      public String capability()
      Sends the IMAP CAPABILITY command and returns the server's raw capability response.

      Use hasCapability(String, String) to test the returned text for a particular capability such as IDLE, MOVE, SORT, or QUOTA.

      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • checkConnection

      public boolean checkConnection()
      Checks whether the underlying TCP socket is currently connected to the IMAP server.

      This performs a low-level socket-state check and does not send an IMAP command. To verify that the server is responsive and the session remains usable, call noop().

      Returns:
      the result; this method never throws ChilkatException

    • clearSessionLog

      public void clearSessionLog()
      Clears the in-memory text returned by getSessionLog().

      Session logging remains enabled or disabled according to getKeepSessionLog().

    • closeMailbox

      public void closeMailbox​(String mailbox)
      Closes the currently selected mailbox while keeping the authenticated IMAP connection open.

      mailbox is retained for backward compatibility but is ignored. It may be the empty string. Messages marked with \Deleted are permanently removed as part of the close operation. After success, getSelectedMailbox() is empty, but another mailbox can be selected on the same connection.

      Parameters:
      mailbox - the mailbox argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • connect

      public void connect​(String domainName)
      Establishes a TCP connection to the IMAP server identified by domainName but does not authenticate.

      domainName may be a hostname, IPv4 address, or IPv6 address. Configure getPort(), getSsl(), getStartTls(), proxy settings, and timeouts before calling this method. The TLS hostname is used for Server Name Indication (SNI) and certificate hostname comparison. Call login(String, String) after the connection succeeds.

      If this method is called while already connected, Chilkat tears down the existing connection and establishes a new connection to domainName. This applies even when domainName names the same server.

      Imap does not automatically reconnect after a connection is dropped. The application must call this method again, authenticate again, reselect a mailbox when needed, and retry the interrupted operation.

      Connection failures can also be caused by DNS, local or remote firewalls, antivirus software, routing, or other network infrastructure outside Chilkat.

      Parameters:
      domainName - the domainName argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • copy

      public void copy​(long msgId, boolean bUid, String copyToMailbox)
      Copies one message from the currently selected mailbox to the destination mailbox in copyToMailbox.

      msgId identifies the source message. If bUid is true, msgId is a UID; otherwise, msgId is a sequence number. The original message remains in the selected mailbox.

      Mailbox names may be supplied as normal Unicode strings. Chilkat automatically handles IMAP modified UTF-7 or UTF-8 mailbox-name encoding as required by the server.

      Parameters:
      msgId - the msgId argument (0 .. 4294967295)
      bUid - the bUid argument
      copyToMailbox - the copyToMailbox argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • copyMultiple

      public void copyMultiple​(MessageSet messageSet, String copyToMailbox)
      Copies the messages identified by the MessageSet in messageSet from the selected mailbox to destination mailbox copyToMailbox using one IMAP command.

      MessageSet.HasUids determines whether messageSet contains UIDs or sequence numbers. For sequence numbers, one invalid value causes the entire command to fail and no messages are copied. For UIDs, nonexistent values are silently ignored and valid messages are copied. The original messages remain in the selected mailbox.

      Mailbox names may be supplied as normal Unicode strings. Chilkat automatically handles IMAP modified UTF-7 or UTF-8 mailbox-name encoding as required by the server.

      Parameters:
      messageSet - the messageSet argument (not null)
      copyToMailbox - the copyToMailbox argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • copySequence

      public void copySequence​(int startSeqNum, int count, String copyToMailbox)
      Copies a contiguous range of messages, identified by sequence number, from the selected mailbox to the destination mailbox in copyToMailbox.

      startSeqNum is the first sequence number and count is the number of messages to copy. IMAP sequence numbers begin at 1 and can change when messages are expunged.

      Mailbox names may be supplied as normal Unicode strings. Chilkat automatically handles IMAP modified UTF-7 or UTF-8 mailbox-name encoding as required by the server.

      Parameters:
      startSeqNum - the startSeqNum argument
      count - the count argument
      copyToMailbox - the copyToMailbox argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • createMailbox

      public void createMailbox​(String mailbox)
      Creates the mailbox named by mailbox on the IMAP server.

      Use the hierarchy delimiter reported in getSeparatorChar() when creating a nested mailbox. In IMAP terminology, mailbox and folder are synonymous.

      Mailbox names may be supplied as normal Unicode strings. Chilkat automatically handles IMAP modified UTF-7 or UTF-8 mailbox-name encoding as required by the server.

      Parameters:
      mailbox - the mailbox argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • deleteMailbox

      public void deleteMailbox​(String mailbox)
      Deletes the mailbox named by mailbox from the IMAP server.

      This deletes the mailbox itself, not merely the messages it contains. Server rules may require the mailbox to be empty first.

      Mailbox names may be supplied as normal Unicode strings. Chilkat automatically handles IMAP modified UTF-7 or UTF-8 mailbox-name encoding as required by the server.

      Parameters:
      mailbox - the mailbox argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • disconnect

      public void disconnect()
      Closes the connection to the IMAP server.

      A failure indicates that the connection could not be closed cleanly; the socket is nevertheless no longer intended for further use. In many applications, a disconnect failure during shutdown can be treated as nonfatal.

      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • examineMailbox

      public void examineMailbox​(String mailbox)
      Opens the mailbox in mailbox as read-only.

      Use this instead of selectMailbox(String) when the application must not change message flags or mailbox state. Successful examination updates properties such as getNumMessages(), getUidValidity(), and getUidNext().

      Mailbox names may be supplied as normal Unicode strings. Chilkat automatically handles IMAP modified UTF-7 or UTF-8 mailbox-name encoding as required by the server.

      Parameters:
      mailbox - the mailbox argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • expunge

      public void expunge()
      Permanently removes all messages marked with the \Deleted flag from the currently selected mailbox.

      The mailbox remains selected and the authenticated connection remains open. Expunging can change sequence numbers for the remaining messages.

      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • expungeAndClose

      public void expungeAndClose()
      Permanently removes all messages marked with \Deleted from the selected mailbox and then closes the mailbox.

      After success, getSelectedMailbox() is empty. The authenticated IMAP connection remains open and can be used to select another mailbox.

      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • fetchAttachment

      public void fetchAttachment​(Email emailObject, int attachmentIndex, String saveToPath)
      Obtains attachment attachmentIndex from the Email in emailObject and writes it to the filesystem path in saveToPath. Attachment indexes are zero-based.

      saveToPath may be a filename, a relative path ending in a filename, or an absolute path ending in a filename. Missing parent directories are not created. An existing file is overwritten. A failed operation should not leave a partial output file.

      If emailObject already contains the attachment bytes, the data is saved without contacting the IMAP server. If emailObject was fetched without attachment bodies, Chilkat uses its ckx-imap-* metadata to locate and download the requested MIME part. The same IMAP session is not required, and a copied Email can be used if the metadata is preserved.

      The corresponding mailbox must be selected when a server fetch is required. If ckx-imap-isUid is YES, the permanent UID is used and the operation can work after reconnecting. If it is NO, the stored value is a sequence number, which can identify a different message after an expunge. UID-based metadata is therefore preferred for deferred attachment operations. The method fails if the referenced message or MIME part no longer exists, such as after the message is moved or expunged.

      Related MIME parts used by an HTML body are not counted as ordinary attachments. Signed and encrypted messages are fetched in full because their complete MIME is required.

      Parameters:
      emailObject - the emailObject argument (not null)
      attachmentIndex - the attachmentIndex argument
      saveToPath - the saveToPath argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • fetchAttachmentBd

      public void fetchAttachmentBd​(Email email, int attachmentIndex, BinData binData)
      Obtains attachment attachmentIndex from the Email in email and stores its bytes in the BinData in binData.

      Attachment indexes are zero-based. binData is always cleared first. On success it contains the complete attachment bytes; on failure it remains empty.

      See fetchAttachment(Email, int, String) for details about downloading attachment data not already present in email.

      Parameters:
      email - the email argument (not null)
      attachmentIndex - the attachmentIndex argument
      binData - the binData argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • fetchAttachmentSb

      public void fetchAttachmentSb​(Email email, int attachmentIndex, String charset, StringBuilder sb)
      Obtains text attachment attachmentIndex from the Email in email, decodes it using the charset in charset, and stores the text in the StringBuilder in sb.

      Attachment indexes are zero-based. sb is always cleared first. On success it contains the complete decoded attachment text; on failure it remains empty. Use this method only for text attachments.

      See fetchAttachment(Email, int, String) for details about downloading data not already present in email.

      Parameters:
      email - the email argument (not null)
      attachmentIndex - the attachmentIndex argument
      charset - the charset argument (not null)
      sb - the sb argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • fetchAttachmentString

      public String fetchAttachmentString​(Email emailObject, int attachmentIndex, String charset)
      Obtains text attachment attachmentIndex from the Email in emailObject and decodes its bytes using the character encoding named by charset.

      Use this only when the attachment contains text. Attachment indexes are zero-based. See fetchAttachment(Email, int, String) for information about downloading attachment data that is not already present in emailObject.

      Parameters:
      emailObject - the emailObject argument (not null)
      attachmentIndex - the attachmentIndex argument
      charset - the charset argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • fetchChunk2

      public void fetchChunk2​(int seqnum, int count, MessageSet failedSet, MessageSet fetchedSet, EmailBundle bundle)
      Attempts to download count full messages beginning with sequence number seqnum.

      failedSet and fetchedSet are cleared before use. failedSet receives sequence numbers that failed or were not yet fetched, fetchedSet receives sequence numbers fetched successfully, and both sets have MessageSet.HasUids set to false. Downloaded messages are appended to the EmailBundle in bundle, which is not cleared.

      Sequence numbers beyond the end of the mailbox are added to failedSet. The method can return success even when failedSet is nonempty; success indicates that the requested range was processed, not that every sequence number existed.

      If a network failure occurs, messages already fetched remain in bundle, fetchedSet retains the successfully fetched sequence numbers, and failedSet contains the failed and not-yet-fetched sequence numbers. Processing stops and the connection must be considered unusable.

      Parameters:
      seqnum - the seqnum argument
      count - the count argument
      failedSet - the failedSet argument (not null)
      fetchedSet - the fetchedSet argument (not null)
      bundle - the bundle argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • fetchEmail

      public void fetchEmail​(boolean headerOnly, long msgId, boolean bUid, Email email)
      Downloads one message or its headers into the Email in email.
      • headerOnly = true: download headers only.
      • headerOnly = false: download the full message.
      • bUid = true: msgId is a UID.
      • bUid = false: msgId is a sequence number.

      On success, email is replaced with the fetched email. On failure, email remains unchanged.

      A header-only result contains no body or attachment bodies, but includes ckx-imap-* metadata for the message identifier, flags, total size, and attachment information. For a full download, ordinary attachment bodies are included according to getAutoDownloadAttachments(). getPeekMode() controls whether a full fetch sets \Seen; a header-only fetch does not set it.

      Parameters:
      headerOnly - the headerOnly argument
      msgId - the msgId argument (0 .. 4294967295)
      bUid - the bUid argument
      email - the email argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • fetchFlags

      public String fetchFlags​(long msgId, boolean bUid)
      Returns the space-separated IMAP flags for the message identified by msgId.

      If bUid is true, msgId is a UID; otherwise, it is a sequence number. A result might be \Flagged \Seen $label1.

      An existing message with no flags returns the empty string. A nonexistent message is an error.

      Parameters:
      msgId - the msgId argument (0 .. 4294967295)
      bUid - the bUid argument
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • fetchMsgSet

      public void fetchMsgSet​(boolean headersOnly, MessageSet msgSet, EmailBundle bundle)
      Downloads the existing messages identified by the MessageSet in msgSet and appends them to the EmailBundle in bundle. bundle is not cleared.
      • headersOnly = true: download headers only.
      • headersOnly = false: download full messages, with ordinary attachments controlled by getAutoDownloadAttachments().

      MessageSet.HasUids determines whether msgSet contains UIDs or sequence numbers. A MessageSet is a true set, so duplicate identifiers are collapsed before any command is sent. Identifiers that do not exist are omitted without causing the method to fail. Do not rely on insertion order; fetched messages are returned in the order supplied by the IMAP server, normally mailbox order.

      If a network failure occurs after some messages have been downloaded, those messages remain appended to bundle, fetching stops immediately, and the connection must be considered unusable. Reconnect, authenticate, and reselect the mailbox before retrying.

      Parameters:
      headersOnly - the headersOnly argument
      msgSet - the msgSet argument (not null)
      bundle - the bundle argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • fetchRange

      public void fetchRange​(boolean headersOnly, int seqnum, int count, EmailBundle bundle)
      Downloads count messages beginning with sequence number seqnum and appends them to the EmailBundle in bundle. bundle is not cleared.
      • headersOnly = true: download headers only.
      • headersOnly = false: download full messages, with ordinary attachments controlled by getAutoDownloadAttachments().

      seqnum and count must both be greater than 0. IMAP sequence numbers begin at 1; passing 0 for seqnum, 0 for count, or a negative count fails without changing bundle. Only messages that exist in the requested sequence-number range are appended. Sequence numbers can change after messages are expunged.

      If a network failure occurs after some messages have been downloaded, those messages remain appended to bundle, fetching stops immediately, and the connection must be considered unusable.

      Parameters:
      headersOnly - the headersOnly argument
      seqnum - the seqnum argument
      count - the count argument
      bundle - the bundle argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • fetchSingleAsMime

      public String fetchSingleAsMime​(long msgId, boolean bUid)
      Downloads one message and returns its MIME source as a string.

      If bUid is true, msgId is a UID; otherwise, msgId is a sequence number. Ordinary attachment bodies are included according to getAutoDownloadAttachments().

      Chilkat interprets the received MIME bytes as UTF-8. MIME using Base64 or quoted-printable transfer encoding is safe because the encoded bytes are ASCII. Raw 8bit or binary content, or unencoded text in another charset such as ISO-8859-1 or Shift_JIS, can be misinterpreted or cause an error. Use fetchSingleBd(long, boolean, BinData) whenever byte-exact MIME is required.

      Parameters:
      msgId - the msgId argument (0 .. 4294967295)
      bUid - the bUid argument
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • fetchSingleAsMimeSb

      public void fetchSingleAsMimeSb​(long msgId, boolean bUid, StringBuilder sbMime)
      Downloads one message's MIME into the StringBuilder in sbMime.

      If bUid is true, msgId is a UID; otherwise, msgId is a sequence number. Ordinary attachment bodies are included according to getAutoDownloadAttachments(). sbMime is cleared before the operation; on failure it remains empty.

      Chilkat interprets the received MIME bytes as UTF-8. MIME using Base64 or quoted-printable transfer encoding is safe because the encoded bytes are ASCII. Raw 8bit or binary content, or unencoded text in another charset such as ISO-8859-1 or Shift_JIS, can be misinterpreted or cause an error. Use fetchSingleBd(long, boolean, BinData) whenever byte-exact MIME is required.

      Parameters:
      msgId - the msgId argument (0 .. 4294967295)
      bUid - the bUid argument
      sbMime - the sbMime argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • fetchSingleBd

      public void fetchSingleBd​(long msgId, boolean bUid, BinData mimeData)
      Downloads one message's MIME bytes into the BinData in mimeData.

      If bUid is true, msgId is a UID; otherwise, it is a sequence number. Ordinary attachment bodies are included according to getAutoDownloadAttachments(), and getPeekMode() controls whether the fetch sets \Seen.

      mimeData is cleared before the operation. On success it contains the downloaded MIME bytes; on failure it remains empty.

      Parameters:
      msgId - the msgId argument (0 .. 4294967295)
      bUid - the bUid argument
      mimeData - the mimeData argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • fetchSingleHeaderAsMime

      public String fetchSingleHeaderAsMime​(long msgId, boolean bUID)
      Downloads and returns the MIME header block for one message, without downloading the body.

      If bUID is true, msgId is a UID; otherwise, msgId is a sequence number.

      Parameters:
      msgId - the msgId argument (0 .. 4294967295)
      bUID - the bUID argument
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getMailAttachFilename

      public String getMailAttachFilename​(Email email, int attachIndex)
      Returns the filename for attachment attachIndex represented by email. Attachment indexes are zero-based.

      This method can obtain the filename from ckx-imap-* metadata in a header-only email even when the attachment body has not been downloaded.

      Parameters:
      email - the email argument (not null)
      attachIndex - the attachIndex argument
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getMailAttachSize

      public int getMailAttachSize​(Email email, int attachIndex)
      Returns the size in bytes of attachment attachIndex represented by email. Attachment indexes are zero-based.

      This method can obtain the size from ckx-imap-* metadata in a header-only email even when the attachment body has not been downloaded.

      Parameters:
      email - the email argument (not null)
      attachIndex - the attachIndex argument
      Returns:
      the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)

    • getMailFlag

      public int getMailFlag​(Email email, String flagName)
      Returns the state of the flag named by flagName from the IMAP metadata stored in the Email in email.
      • 1: the flag is set.
      • 0: the flag is not set.
      • -1: the required ckx-imap-* metadata is missing.

      Standard flags include \Seen, \Answered, \Flagged, \Draft, and \Deleted. Custom keywords such as $label1 or NonJunk are also supported.

      Integer-returning methods do not use LastMethodSuccess to report this condition; test the return value directly.

      Parameters:
      email - the email argument (not null)
      flagName - the flagName argument (not null)
      Returns:
      the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)

    • getMailNumAttach

      public int getMailNumAttach​(Email email)
      Returns the number of ordinary attachments represented by email.

      This method also works with a header-only email or an email fetched while getAutoDownloadAttachments() was false. In those cases it reads the ckx-imap-numAttach metadata, even though the Email object's downloaded attachment count can be 0.

      Parameters:
      email - the email argument (not null)
      Returns:
      the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)

    • getMailSize

      public int getMailSize​(Email email)
      Returns the complete server-reported size of the Email in email, in bytes, including attachment data.

      This value may be available even when only the message headers were downloaded.

      Parameters:
      email - the email argument (not null)
      Returns:
      the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)

    • getMailboxStatus

      public String getMailboxStatus​(String mailbox)
      Sends the IMAP STATUS command for the mailbox in mailbox and returns the reported values as XML attributes.
      • messages: total number of messages.
      • recent: messages having the \Recent flag.
      • uidnext: expected UID for the next appended message.
      • uidvalidity: mailbox UID-validity value.
      • unseen: messages without the \Seen flag. 

      <status messages="240" recent="0" uidnext="3674" uidvalidity="3" unseen="213" />

      Mailbox names may be supplied as normal Unicode strings. Chilkat automatically handles IMAP modified UTF-7 or UTF-8 mailbox-name encoding as required by the server.

      Parameters:
      mailbox - the mailbox argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getQuota

      public String getQuota​(String quotaRoot)
      Sends the IMAP GETQUOTA command for the quota root in quotaRoot and returns the server response as JSON.

      The server must advertise the IMAP QUOTA capability.

      Parameters:
      quotaRoot - the quotaRoot argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getQuotaRoot

      public String getQuotaRoot​(String mailboxName)
      Sends the IMAP GETQUOTAROOT command for the mailbox in mailboxName and returns the server response as JSON. The server must advertise the IMAP QUOTA capability.

      A response can contain both the mailbox-to-root mapping and the quota values: 

      {
   "QUOTAROOT": {"mailbox":"Inbox","root":"Mailbox"},
   "QUOTA": {"root":"Mailbox","resource":"STORAGE","used":9,"max":256000}
 }

      Mailbox names may be supplied as normal Unicode strings. Chilkat automatically handles IMAP modified UTF-7 or UTF-8 mailbox-name encoding as required by the server.

      Parameters:
      mailboxName - the mailboxName argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • getServerCert

      public void getServerCert​(Cert cert)
      Stores the certificate presented by the IMAP server for the current or most recent TLS connection in the Cert object supplied as cert.

      This is useful for certificate inspection, diagnostics, or implementing application-specific trust checks.

      Parameters:
      cert - the cert argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • hasCapability

      public boolean hasCapability​(String name, String capabilityResponse)
      Tests whether the capability named by name appears in the raw capability response in capabilityResponse.

      capabilityResponse is typically the string returned by capability(). Capability-name matching follows IMAP capability-token semantics.

      Parameters:
      name - the name argument (not null)
      capabilityResponse - the capabilityResponse argument (not null)
      Returns:
      the result; this method never throws ChilkatException

    • idleCheck

      public String idleCheck​(int timeoutMs)
      Waits up to timeoutMs milliseconds for unsolicited mailbox updates after idleStart() has entered IMAP IDLE mode.

      timeoutMs = 0 performs a strict poll: it checks for already available data and returns immediately. Positive values wait for up to the requested time, including very large values. If the connection is lost while waiting, the method fails.

      This method does not send a polling command. It consumes the notifications currently waiting on the existing connection and returns them as XML. A second call returns only notifications that arrived after the previous call.

      • flags: flags changed for a message.
      • expunge: a sequence number was removed.
      • exists: the mailbox message count changed.
      • recent: the recent-message count changed.
      • raw: an unrecognized response line retained for diagnostics. 

      <idle><exists>115</exists><recent>1</recent></idle>

      When no update is available, the result is <idle></idle>. An exists notification does not automatically change getNumMessages().

      Chilkat does not automatically refresh IDLE. The application should periodically call idleDone() and idleStart(), typically before 29 minutes have elapsed, to prevent servers with a 30-minute limit from dropping the connection.

      Parameters:
      timeoutMs - the timeoutMs argument
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • idleDone

      public void idleDone()
      Ends IMAP IDLE mode by sending the protocol's DONE continuation.

      The authenticated connection remains open and usable. Calling this method when IDLE is not active fails.

      Applications maintaining a long-lived IDLE connection should call this method shortly before the server's IDLE limit, commonly at about 29 minutes, and then immediately call idleStart() again.

      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • idleStart

      public void idleStart()
      Sends the IMAP IDLE command and begins listening for unsolicited mailbox updates.

      The session must be connected, authenticated, and have a mailbox selected with selectMailbox(String) or examineMailbox(String). The server must advertise the IDLE capability.

      Calling this method while IDLE is already active fails. While IDLE is active, any other method that sends an IMAP command also fails; call idleDone() first.

      Chilkat does not automatically renew IDLE. To avoid common server time limits, the application should end and restart IDLE before the server timeout, typically about every 29 minutes.

      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • isConnected

      public boolean isConnected()
      Returns the last known connection state without sending data to the IMAP server.

      A true result does not prove that an idle connection is still usable. Call noop() to send a command and verify that the server responds.

      Returns:
      the result; this method never throws ChilkatException

    • isLoggedIn

      public boolean isLoggedIn()
      Indicates whether this object is in an authenticated IMAP session.

      This reports the last known state and does not send a command to the server.

      Returns:
      the result; this method never throws ChilkatException

    • login

      public void login​(String loginName, String password)
      Authenticates the connected IMAP session using the login name in loginName and the credential in password.

      Call connect(String) first. The mechanism is selected by getAuthMethod().

      For XOAUTH2, loginName is the normal IMAP login name or email address and password is the raw OAuth 2.0 access token without a Bearer prefix. A failed XOAUTH2 login leaves the connection open so the application may correct the credentials and try again.

      Do not call this method again after the session is already authenticated. A repeated login attempt fails, although the existing authenticated session remains logged in.

      Parameters:
      loginName - the loginName argument (not null)
      password - the password argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • loginSecure

      public void loginSecure​(SecureString loginName, SecureString password)
      Authenticates the connected IMAP session using the SecureString login name in loginName and credential in password.

      This is the secure-string counterpart of login(String, String). The authentication mechanism is selected by getAuthMethod().

      For XOAUTH2, loginName contains the normal login name or email address and password contains the raw access token without a Bearer prefix.

      Parameters:
      loginName - the loginName argument (not null)
      password - the password argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • logout

      public void logout()
      Sends the IMAP LOGOUT command and ends the authenticated session.

      The server normally closes the connection as part of a successful logout.

      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • mbxList

      public void mbxList​(boolean subscribed, String reference, String mbxPattern, Mailboxes mboxes)
      Lists matching mailboxes and appends them to the Mailboxes object in mboxes. mboxes is not cleared on success, so repeated calls on the same object can add duplicate entries. If the method fails, mboxes is unchanged.
      • subscribed = true: list only subscribed mailboxes.
      • subscribed = false: list all matching mailboxes.

      reference is the IMAP reference name, usually an empty string. mbxPattern is the mailbox pattern: * matches zero or more hierarchy levels, while % matches one hierarchy level.

      Applications may use normal Unicode mailbox names and patterns. Chilkat automatically handles IMAP modified UTF-7 or UTF-8 mailbox-name encoding as required by the server.

      The method also updates getSeparatorChar() from the server's response.

      Parameters:
      subscribed - the subscribed argument
      reference - the reference argument (not null)
      mbxPattern - the mbxPattern argument (not null)
      mboxes - the mboxes argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • moveMessages

      public void moveMessages​(MessageSet messageSet, String destFolder)
      Moves the messages identified by the MessageSet in messageSet from the selected mailbox to destination mailbox destFolder using one IMAP MOVE command.

      The server must advertise the MOVE capability. If it does not, this method fails and does not emulate the operation with copy, delete, and expunge commands.

      MessageSet.HasUids determines whether messageSet contains UIDs or sequence numbers. For sequence numbers, one invalid value causes complete failure and nothing is moved. For UIDs, nonexistent values are silently ignored and valid messages are moved.

      Mailbox names may be supplied as normal Unicode strings. Chilkat automatically handles IMAP modified UTF-7 or UTF-8 mailbox-name encoding as required by the server.

      Parameters:
      messageSet - the messageSet argument (not null)
      destFolder - the destFolder argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • noop

      public void noop()
      Sends the IMAP NOOP command and waits for the server response.

      This is useful for verifying that an existing authenticated connection is still responsive and for receiving unsolicited mailbox-state updates.

      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • queryMbx

      public void queryMbx​(String criteria, boolean bUid, MessageSet msgSet)
      Searches the selected mailbox using the IMAP criteria in criteria and stores matching identifiers in the MessageSet in msgSet.

      On success, msgSet is replaced with the result. If bUid is true, msgSet contains UIDs and MessageSet.HasUids is true; otherwise, msgSet contains sequence numbers and MessageSet.HasUids is false. If the method fails, msgSet is unchanged. getSearchCharset() applies when the criteria contain non-ASCII text.

      For the special criterion new-email, Chilkat records each UIDNEXT received from SELECT, EXAMINE, or another IMAP response and uses it as the baseline for detecting later UIDs. If no UIDNEXT is available, Chilkat searches for messages having the \Recent flag. Results are always UIDs regardless of bUid, and an empty result clears msgSet.

      When getSortCriteria() is nonempty, Chilkat uses IMAP SORT if the server supports it. Otherwise, it automatically falls back to an ordinary SEARCH.

      Parameters:
      criteria - the criteria argument (not null)
      bUid - the bUid argument
      msgSet - the msgSet argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • queryThread

      public void queryThread​(String threadAlg, String searchCriteria, boolean bUid, JsonObject json)
      Sends the IMAP THREAD command for the selected mailbox.

      threadAlg is the threading algorithm, commonly ORDEREDSUBJECT or REFERENCES. searchCriteria contains ordinary IMAP search criteria and is interpreted using getSearchCharset(). If bUid is true, message identifiers in the result are UIDs; otherwise, they are sequence numbers.

      On success, json is completely replaced with the thread hierarchy. On failure, json is unchanged; there is no partial-success JSON result.

      The returned JSON has a top-level threads array. Each element represents one thread, and nested arrays encode parent/child relationships. For example: 

      {"threads":[[1],[2],[3]]}

      The server must advertise the IMAP THREAD capability and support the selected algorithm.

      Parameters:
      threadAlg - the threadAlg argument (not null)
      searchCriteria - the searchCriteria argument (not null)
      bUid - the bUid argument
      json - the json argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • rawCommandBd

      public void rawCommandBd​(BinData bdCmd, BinData bdResp)
      Sends the raw IMAP command bytes in the BinData in bdCmd and stores the raw response bytes in bdResp.

      bdCmd contains the command without an IMAP command tag or trailing CRLF; Chilkat supplies both. bdResp is cleared and replaced with the response.

      Use raw commands only for rare server extensions that are not otherwise exposed by the API, have an expected one-line response, and do not change Imap object state such as the selected mailbox, message count, UidNext, or UidValidity. State-changing raw commands can leave cached properties inconsistent with the server.

      Parameters:
      bdCmd - the bdCmd argument (not null)
      bdResp - the bdResp argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • refetchMailFlags

      public void refetchMailFlags​(Email email)
      Fetches the current IMAP flags for the server message represented by email and updates its ckx-imap-* metadata headers.

      Chilkat reads the identifier from ckx-imap-uid and checks ckx-imap-isUid to determine whether it is a UID or sequence number. A copied Email can be used as long as this metadata is preserved.

      When ckx-imap-isUid is NO, the stored sequence number may identify a different message after an expunge. UID-based emails are preferred for later operations. Methods such as getMailFlag(Email, String) read the refreshed flag metadata.

      Parameters:
      email - the email argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • renameMailbox

      public void renameMailbox​(String fromMailbox, String toMailbox)
      Renames the mailbox in fromMailbox to the name in toMailbox.

      Changing hierarchy components can also move a mailbox within the server's folder tree, for example from INBOX.old.project to INBOX.archive.project.

      Mailbox names may be supplied as normal Unicode strings. Chilkat automatically handles IMAP modified UTF-7 or UTF-8 mailbox-name encoding as required by the server.

      Parameters:
      fromMailbox - the fromMailbox argument (not null)
      toMailbox - the toMailbox argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • selectMailbox

      public void selectMailbox​(String mailbox)
      Opens the mailbox in mailbox for read-write access.

      A mailbox must be selected before message fetch, search, flag, copy, move, or expunge operations that act on mailbox contents. Successful selection updates getSelectedMailbox(), getNumMessages(), getUidValidity(), and related mailbox-state properties.

      Use examineMailbox(String) when read-only access is required.

      Mailbox names may be supplied as normal Unicode strings. Chilkat automatically handles IMAP modified UTF-7 or UTF-8 mailbox-name encoding as required by the server.

      Parameters:
      mailbox - the mailbox argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • sendRawCommand

      public String sendRawCommand​(String cmd)
      Sends the raw IMAP command text in cmd and returns the raw server response.

      Pass the command itself, such as NOOP, without an IMAP command tag or trailing CRLF. Chilkat generates the tag and command line termination.

      Use raw commands only for rare server extensions that are not otherwise exposed by the API, have an expected one-line response, and do not change Imap object state such as the selected mailbox, message count, UidNext, or UidValidity. State-changing raw commands can leave cached properties inconsistent with the server.

      Parameters:
      cmd - the cmd argument (not null)
      Returns:
      the result (never null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setDecryptCert

      public void setDecryptCert​(Cert cert)
      Specifies the Cert in cert for decrypting S/MIME messages downloaded by this Imap object.

      The certificate must have access to its associated private key. Use setDecryptCert2(Cert, PrivateKey) when the private key is supplied separately.

      Parameters:
      cert - the cert argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setDecryptCert2

      public void setDecryptCert2​(Cert cert, PrivateKey key)
      Specifies the certificate in cert and its separately supplied PrivateKey in key for decrypting S/MIME messages.

      Use this when the certificate object does not already provide access to the private key.

      Parameters:
      cert - the cert argument (not null)
      key - the key argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setFlag

      public void setFlag​(long msgId, boolean bUid, String flagName, int value)
      Sets or clears one flag on the message identified by msgId in the selected mailbox.

      If bUid is true, msgId is a UID; otherwise, it is a sequence number. flagName is the flag name, and value is 1 to set the flag or 0 to clear it.

      Standard flags include \Deleted, \Seen, \Answered, \Flagged, and \Draft. Server-supported custom keywords may also be used.

      Parameters:
      msgId - the msgId argument (0 .. 4294967295)
      bUid - the bUid argument
      flagName - the flagName argument (not null)
      value - the value argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setFlags

      public void setFlags​(MessageSet messageSet, String flagName, int value)
      Sets or clears one flag for every identifier in the MessageSet supplied in messageSet.

      flagName is the flag name, and value is 1 to set it or 0 to clear it. MessageSet.HasUids determines whether the identifiers are UIDs or sequence numbers. Chilkat sends one IMAP STORE or UID STORE command containing the complete identifier set.

      IMAP bulk flag changes are not atomic and have no all-or-nothing rollback. Changes applied before a failure remain applied. For UID-based operations, nonexistent UIDs are silently ignored as required by IMAP. For sequence-number operations, an out-of-range sequence number causes the server to return an error; whether valid sequence numbers in the same command were changed before that error is server-dependent.

      This method changes server state only. It does not update metadata in any previously fetched Email objects.

      Parameters:
      messageSet - the messageSet argument (not null)
      flagName - the flagName argument (not null)
      value - the value argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setMailFlag

      public void setMailFlag​(Email email, String flagName, int value)
      Sets or clears a flag for the server message represented by the Email in email.

      Chilkat reads the message identifier from ckx-imap-uid and uses ckx-imap-isUid to determine whether the value is a UID or sequence number. flagName is the flag name, and value is 1 to set it or 0 to clear it. The method fails if the required metadata is absent.

      A copied Email can be used as long as the metadata is preserved. When ckx-imap-isUid is NO, the stored value is a sequence number and may no longer identify the same message after an expunge. UID-based emails are preferred for operations performed later or after reconnecting.

      Setting \Deleted marks the message for deletion; call expunge() to remove it permanently.

      Parameters:
      email - the email argument (not null)
      flagName - the flagName argument (not null)
      value - the value argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setQuota

      public void setQuota​(String quotaRoot, String resource, int quota)
      Sends the IMAP SETQUOTA command for quota root quotaRoot.

      resource is STORAGE to set the combined message-storage limit or MESSAGE to set the message-count limit. For STORAGE, quota is measured in units of 1024 octets; for example, 500000 represents approximately 500,000,000 bytes.

      The server must support the IMAP QUOTA extension and the requested resource type.

      Parameters:
      quotaRoot - the quotaRoot argument (not null)
      resource - the resource argument (not null)
      quota - the quota argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setSslClientCert

      public void setSslClientCert​(Cert cert)
      Specifies the client certificate in cert for TLS client-certificate authentication.

      Most IMAP servers do not require a client certificate. When one is required, cert must provide access to the corresponding private key.

      Parameters:
      cert - the cert argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setSslClientCertPem

      public void setSslClientCertPem​(String pemDataOrFilename, String pemPassword)
      Specifies a TLS client certificate and private key from PEM data or a PEM file.

      pemDataOrFilename may contain the PEM text itself or a local filesystem path to the PEM file; Chilkat detects which form was supplied. pemPassword contains the password when the private key is encrypted.

      Parameters:
      pemDataOrFilename - the pemDataOrFilename argument (not null)
      pemPassword - the pemPassword argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setSslClientCertPfx

      public void setSslClientCertPfx​(String pfxFilename, String pfxPassword)
      Specifies a TLS client certificate and private key from a PKCS #12/PFX file.

      pfxFilename is the local filesystem path of the .pfx or .p12 file, and pfxPassword contains its password.

      Parameters:
      pfxFilename - the pfxFilename argument (not null)
      pfxPassword - the pfxPassword argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • sshAuthenticatePk

      public void sshAuthenticatePk​(String sshLogin, SshKey privateKey)
      Authenticates the SSH tunnel using the username in sshLogin and the SshKey private key in privateKey.

      Call sshOpenTunnel(String, int) first. The corresponding public key must already be authorized for sshLogin on the SSH server. After authentication, call connect(String) and login(String, String) for the IMAP server.

      Parameters:
      sshLogin - the sshLogin argument (not null)
      privateKey - the privateKey argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • sshAuthenticatePw

      public void sshAuthenticatePw​(String sshLogin, String sshPassword)
      Authenticates the SSH tunnel using the username in sshLogin and password in sshPassword.

      Call sshOpenTunnel(String, int) first. After SSH authentication succeeds, call connect(String) and login(String, String); the IMAP traffic then flows through the tunnel automatically.

      Parameters:
      sshLogin - the sshLogin argument (not null)
      sshPassword - the sshPassword argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • sshCloseTunnel

      public void sshCloseTunnel()
      Closes the SSH tunnel opened by sshOpenTunnel(String, int).

      Any IMAP connection using that tunnel must no longer be used after the tunnel is closed.

      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • sshOpenTunnel

      public void sshOpenTunnel​(String sshHostname, int sshPort)
      Connects to the SSH server in sshHostname on port sshPort and prepares an SSH tunnel for the later IMAP connection.

      Port 22 is the usual SSH port. After this succeeds, authenticate with sshAuthenticatePw(String, String) or sshAuthenticatePk(String, SshKey), then call connect(String) and login(String, String) for IMAP.

      Parameters:
      sshHostname - the sshHostname argument (not null)
      sshPort - the sshPort argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • storeFlags

      public void storeFlags​(long msgId, boolean bUid, String flagNames, int value)
      Sets or clears multiple flags on one message in the selected mailbox.

      If bUid is true, msgId is a UID; otherwise, it is a sequence number. flagNames is a space-separated list such as \Seen \Answered $label1. value is 1 to set all listed flags or 0 to clear them.

      The operation uses IMAP STORE or UID STORE and is not transactional. A nonexistent UID can be silently ignored and the command can still succeed. An invalid sequence number causes failure. This method changes server state only and does not update metadata in previously fetched Email objects.

      Parameters:
      msgId - the msgId argument (0 .. 4294967295)
      bUid - the bUid argument
      flagNames - the flagNames argument (not null)
      value - the value argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • subscribe

      public void subscribe​(String mailbox)
      Subscribes the authenticated IMAP account to the mailbox named by mailbox.

      Subscription controls which mailboxes are returned by subscribed-mailbox listing operations; it does not create the mailbox.

      Mailbox names may be supplied as normal Unicode strings. Chilkat automatically handles IMAP modified UTF-7 or UTF-8 mailbox-name encoding as required by the server.

      Parameters:
      mailbox - the mailbox argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • unsubscribe

      public void unsubscribe​(String mailbox)
      Removes the subscription to the mailbox named by mailbox.

      The mailbox itself and its messages are not deleted.

      Mailbox names may be supplied as normal Unicode strings. Chilkat automatically handles IMAP modified UTF-7 or UTF-8 mailbox-name encoding as required by the server.

      Parameters:
      mailbox - the mailbox argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • useCertVault

      public void useCertVault​(XmlCertVault vault)
      Associates the XmlCertVault in vault with this Imap object as a source of certificates and private keys for S/MIME operations.

      Only one vault can be associated at a time. Calling this method again replaces the previously associated vault.

      Parameters:
      vault - the vault argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • useSsh

      public void useSsh​(Ssh ssh)
      Uses an already connected and authenticated Ssh object as the transport for subsequent IMAP connections.

      SSH supports multiple logical channels, so the same SSH connection may be shared by IMAP and other Chilkat objects. Call this method before connect(String).

      Parameters:
      ssh - the ssh argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • useSshTunnel

      public void useSshTunnel​(Socket tunnel)
      Uses the existing SSH tunnel represented by the Socket in tunnel for subsequent IMAP connections.

      This allows a tunnel to be shared with other objects. Call this method before connect(String).

      Parameters:
      tunnel - the tunnel argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • setProgressListener

      public void setProgressListener​(ProgressListener listener)
      Installs the listener that receives this object's progress events (abortCheck, percentDone, progressInfo) during its long-running methods; replaces any listener or lambda installed before; null removes it.
      Parameters:
      listener - the listener, or null
      Throws:
      IllegalStateException - if called from inside one of this object's own callbacks

    • getProgressListener

      public ProgressListener getProgressListener()
      Returns the installed listener, or null.
      Returns:
      the listener installed with setProgressListener(ProgressListener) or one of the on... methods

    • onAbortCheck

      public void onAbortCheck​(BooleanSupplier callback)
      Installs a listener whose only callback is abortCheck: called every HeartbeatMs milliseconds during a long-running method; return true to abort it. Replaces any listener installed before.
      Parameters:
      callback - the callback, or null to remove the listener

    • onPercentDone

      public void onPercentDone​(IntPredicate callback)
      Installs a listener whose only callback is percentDone: called with the completion percentage (0..100) as a long-running method progresses; return true to abort it. Replaces any listener installed before.
      Parameters:
      callback - the callback, or null to remove the listener

    • onProgressInfo

      public void onProgressInfo​(BiConsumer<String,​String> callback)
      Installs a listener whose only callback is progressInfo: called with a name/value pair of progress information as a long-running method proceeds. Replaces any listener installed before.
      Parameters:
      callback - the callback, or null to remove the listener