Package com.chilkatsoft.chilkat2

Class MailMan

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

Send, receive, secure, and troubleshoot email with SMTP and POP3.

Chilkat.MailMan is a full-featured email client class for applications that need SMTP sending and POP3 receiving. It supports secure authentication, MIME rendering, attachments, S/MIME signing and encryption, OAuth2, TLS/STARTTLS, proxy and SSH tunnel routing, POP3 download and delete workflows, delivery status notifications, and detailed diagnostics for troubleshooting mail server communication.

SMTP sending

Send email messages, MIME content, bundles of messages, and signed or encrypted S/MIME mail through SMTP servers.

POP3 receiving

Connect to POP3 mailboxes, list messages, download email, retrieve headers, and control when messages are deleted from the server.

Secure authentication

Use passwords, OAuth2 access tokens, TLS, STARTTLS, client certificates, and secret-backed credentials where appropriate.

MIME and attachments

Render, send, retrieve, and process MIME messages, including HTML bodies, alternative bodies, embedded images, and file attachments.

S/MIME support

Work with certificates and private keys to sign, verify, encrypt, and decrypt email messages.

Diagnostics and routing

Troubleshoot SMTP and POP3 sessions with detailed logs, status codes, server responses, proxy settings, and SSH tunnel support.

Common pattern: Configure the SMTP or POP3 server settings, choose the security and authentication method, send or retrieve messages, then inspect server status, response text, and LastErrorText when troubleshooting provider- specific behavior.

For an extended overview, see MailMan 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

    • MailMan

      public MailMan()
      Creates a new MailMan object.

  • Method Details

    • getAbortCurrent

      public boolean getAbortCurrent()
      Set this property to true to request that the currently running operation be aborted.

      This applies to methods that may take time to complete, such as methods that perform network communication or lengthy file operations. Methods that always complete quickly are generally not affected.

      If no method is currently running, the property is automatically reset to false when the next method call begins. When an abort actually occurs, Chilkat resets this property to false.

      Both synchronous and asynchronous method calls can be aborted. A synchronous method can be aborted by setting this property from another thread.

      Returns:
      the value of the AbortCurrent property

    • setAbortCurrent

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

    • getAllOrNone

      public boolean getAllOrNone()
      Determines whether an email should be sent when one or more recipients are rejected by the SMTP server.

      The default value is false, which means Chilkat continues sending even if some recipients are rejected.

      When set to true, the email is not sent to any recipients if the SMTP server rejects any recipient address.

      Important: This property only works when SMTP pipelining is disabled. Because getSmtpPipelining() is true by default, set SmtpPipelining = false when all-or-none behavior is required.

      Note: SMTP servers do not always verify recipient addresses. Even when they do, the server can usually verify only addresses within domains it controls.

      Returns:
      the value of the AllOrNone property

    • setAllOrNone

      public void setAllOrNone​(boolean value)
      Sets the AllOrNone property; see getAllOrNone().
      Parameters:
      value - the new value

    • getAutoFix

      public boolean getAutoFix()
      Controls whether Chilkat automatically selects the SMTP and POP3 TLS mode from a standard port number when a connection is prepared.
      • SMTP port 465: implicit TLS (getSmtpSsl() = true).
      • SMTP port 587: explicit TLS using STARTTLS.
      • SMTP port 25: no TLS is implied.
      • POP3 port 995: implicit TLS (getPopSsl() = true).
      • POP3 port 110: no TLS is implied.

      The default value is true. For these standard ports, Chilkat sets the related TLS properties to a consistent combination before connecting, so conflicting implicit and explicit TLS settings do not remain in effect.

      If the configured port is nonstandard, AutoFix does not change the TLS properties. The application must set the desired implicit, required-explicit, opportunistic-explicit, or unencrypted mode explicitly.

      Important: AutoFix is applied when Chilkat prepares the connection. Assigning a port number does not immediately rewrite the visible property values.

      Returns:
      the value of the AutoFix property

    • setAutoFix

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

    • getAutoGenMessageId

      public boolean getAutoGenMessageId()
      Determines whether Chilkat automatically generates a unique Message-ID header when an email is sent.

      The default behavior is to generate a new unique Message-ID at send time. This allows the same Email object to be reused without accidentally sending duplicate message IDs.

      If duplicate message IDs are used, some SMTP servers may treat the message as a duplicate and discard it.

      When automatic generation is enabled, calling GetHeaderField("Message-ID") before sending will not necessarily show the actual message ID that Chilkat sends.

      Set this property to false to prevent Chilkat from automatically generating the Message-ID header.

      Returns:
      the value of the AutoGenMessageId property

    • setAutoGenMessageId

      public void setAutoGenMessageId​(boolean value)
      Sets the AutoGenMessageId property; see getAutoGenMessageId().
      Parameters:
      value - the new value

    • getAutoSmtpRset

      public boolean getAutoSmtpRset()
      When true, Chilkat automatically sends the SMTP RSET command before sending a new email over an already-open SMTP connection.

      This helps ensure the SMTP session is in a clean state before the next email is sent.

      The default value is false.

      Note: This property only applies when reusing an existing SMTP connection.

      Returns:
      the value of the AutoSmtpRset property

    • setAutoSmtpRset

      public void setAutoSmtpRset​(boolean value)
      Sets the AutoSmtpRset property; see getAutoSmtpRset().
      Parameters:
      value - the new value

    • getAutoUnwrapSecurity

      public boolean getAutoUnwrapSecurity()
      Determines whether Chilkat automatically unwraps digitally signed or encrypted email when the message is downloaded or loaded from MIME.

      The default value is true. When enabled, Chilkat verifies signatures and decrypts encrypted content when possible. The results are made available through the email object's security-related properties and methods.

      Set this property to false if you want signed or encrypted attachments, such as .p7m or .p7s files, to remain as ordinary attachments.

      Important: Signature verification and decryption must occur when the original MIME is first loaded. After MIME is parsed into Chilkat's internal email object format, the exact original MIME bytes are no longer available, and the signature can no longer be verified.

      Returns:
      the value of the AutoUnwrapSecurity property

    • setAutoUnwrapSecurity

      public void setAutoUnwrapSecurity​(boolean value)
      Sets the AutoUnwrapSecurity property; see getAutoUnwrapSecurity().
      Parameters:
      value - the new value

    • getClientIpAddress

      public String getClientIpAddress()
      Sets the local IP address to use when connecting from a computer that has multiple network interfaces or multiple IP addresses.

      For most computers, this property should be left unset. Chilkat will automatically use the default local IP address.

      The value should be 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)

    • getConnectFailReason

      public int getConnectFailReason()
      Contains a numeric code describing the result of the last connection attempt. This applies to the last connection made, or attempted, by any method.

      Code Meaning

      0 Success.

      1 Empty hostname.

      2 DNS lookup failed.

      3 DNS timeout.

      4 Aborted by the application.

      5 Internal failure.

      6 Connection timed out.

      7 Connection rejected, or failed for another reason.

      100 TLS internal error.

      101 Failed to send the TLS client hello.

      102 Unexpected TLS handshake message.

      103 Failed to read the TLS server hello.

      104 No server certificate was received.

      105 Unexpected TLS protocol version.

      106 Server certificate verification failed.

      107 Unacceptable TLS protocol version.

      109 Failed to read TLS handshake messages.

      110 Failed to send client certificate handshake message.

      111 Failed to send client key exchange handshake message.

      112 Client certificate private key is not accessible.

      113 Failed to send client certificate verify handshake message.

      114 Failed to send change cipher spec handshake message.

      115 Failed to send finished handshake message.

      116 The server's finished message is invalid.

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

    • getConnectTimeout

      public int getConnectTimeout()
      The maximum number of seconds to wait while attempting to connect to an SMTP or POP3 server.

      The default value is 30 seconds.

      Returns:
      the value of the ConnectTimeout property

    • setConnectTimeout

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

    • getDsnEnvid

      public String getDsnEnvid()
      The DsnEnvid property specifies the SMTP DSN ENVID value, which is an arbitrary identifier attached to the SMTP envelope. The same value is typically returned in DSN responses so the sending application can correlate delivery notifications with the original outbound email.

      Common choices for DsnEnvid include:

      • An internal message ID:
        MSG-10004521
      • A GUID or UUID:
        550e8400-e29b-41d4-a716-446655440000
      • An order or transaction number:
        ORDER-847291
      • A timestamp-based identifier:
        MAIL-20260515-153045-001
      • A composite identifier combining application, customer, and message IDs:
        billing|cust-9182|invoice-44381

      The value should uniquely identify the outbound email within your application. It does not need to match the MIME Message-ID header, although some applications choose to use the same identifier for both.

      About SMTP DSN

      SMTP DSN means Delivery Status Notification. It is an optional SMTP service extension defined by RFC 3461 that allows the sender to request delivery-status reports from the SMTP server.

      DSN allows an application to request notifications such as:

      • Successful delivery
      • Delivery failure
      • Delayed delivery

      It also allows the sender to specify whether the returned notification should include the full original message or only the message headers.

      In MailMan, DSN behavior is controlled using:

      • DsnEnvid — sets the SMTP ENVID envelope identifier.
      • getDsnNotify() — controls when notifications are requested, such as SUCCESS, FAILURE, DELAY, or NEVER.
      • getDsnRet() — controls whether DSN responses include the full message or only headers.

      DSN is an optional SMTP extension and is not supported by all SMTP servers. A server supports DSN only if it advertises the DSN capability in response to the SMTP EHLO command.

      The isSmtpDsnCapable() method can be used to determine whether the SMTP server supports DSN.

      Even when DSN is supported, some SMTP servers or downstream mail systems may ignore or partially honor DSN requests.

      Returns:
      the value of the DsnEnvid property

    • setDsnEnvid

      public void setDsnEnvid​(String value)
      Sets the DsnEnvid property; see getDsnEnvid().
      Parameters:
      value - the new value (not null)

    • getDsnNotify

      public String getDsnNotify()
      Sets the SMTP DSN NOTIFY parameter used when sending email.

      The value may be left empty, set to NEVER, or set to a comma-separated combination of SUCCESS, FAILURE, and DELAY.

      Returns:
      the value of the DsnNotify property

    • setDsnNotify

      public void setDsnNotify​(String value)
      Sets the DsnNotify property; see getDsnNotify().
      Parameters:
      value - the new value (not null)

    • getDsnRet

      public String getDsnRet()
      Sets the SMTP DSN RET parameter used when sending email.

      The value may be left empty, set to FULL to request the full message in DSN notifications, or set to HDRS to request only the message headers.

      Returns:
      the value of the DsnRet property

    • setDsnRet

      public void setDsnRet​(String value)
      Sets the DsnRet property; see getDsnRet().
      Parameters:
      value - the new value (not null)

    • getEmbedCertChain

      public boolean getEmbedCertChain()
      When true, Chilkat embeds the signing certificate chain in signed email.

      Certificates are included up to, but not including, the root certificate. If getIncludeRootCert() is also true, the root CA certificate is included as well.

      The default value is false

      Returns:
      the value of the EmbedCertChain property

    • setEmbedCertChain

      public void setEmbedCertChain​(boolean value)
      Sets the EmbedCertChain property; see getEmbedCertChain().
      Parameters:
      value - the new value

    • getEnableSecrets

      public boolean getEnableSecrets()
      Enables automatic resolution of passwords and credentials from secure local storage.

      When set to true, supported properties and methods can accept a Chilkat secret specification string instead of a literal password. Secret specification strings begin with !!.

      Chilkat resolves secrets from:

      • Windows Credential Manager on Windows.
      • Apple Keychain on macOS.

      The secret specification format is: !![appName|]service[|domain]|username

      This applies to getPopPassword(), getSmtpPassword(), getHttpProxyPassword(), getSocksPassword(), getPopPasswordBase64(), and sshAuthenticatePw(String, String).

      The default value is false.

      Returns:
      the value of the EnableSecrets property

    • setEnableSecrets

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

    • getFilter

      public String getFilter()
      Specifies a filter expression applied by methods such as LoadXmlFile, LoadXmlString, LoadMbx, CopyMail, and TransferMail.

      When a filter is present, only emails matching the expression are returned. For TransferMail, only matching emails are removed from the mail server.

      Example expressions:

      Body like "mortgage rates*"
      Subject contains "update" and From contains "chilkat"
      To = "info@chilkatsoft.com"

      Rules for filter expressions:

      • Any MIME header field name may be used. Header names are case-insensitive.
      • Literal strings are enclosed in double quotes.
      • String matching is case-insensitive.
      • The * wildcard matches zero or more characters.
      • Parentheses may be used to control precedence.
      • Logical operators are AND, OR, and NOT.
      • String comparison operators include CONTAINS and LIKE.

      Note: Filtering works on text strings only, not dates or numbers.

      Returns:
      the value of the Filter property

    • setFilter

      public void setFilter​(String value)
      Sets the Filter property; see getFilter().
      Parameters:
      value - the new value (not null)

    • getHeartbeatMs

      public int getHeartbeatMs()
      Sets the interval, in milliseconds, between AbortCheck event callbacks.

      This allows an application to periodically decide whether a long-running operation should be aborted.

      The default value is 0, which means no AbortCheck callbacks are generated.

      Returns:
      the value of the HeartbeatMs property

    • setHeartbeatMs

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

    • getHeloHostname

      public String getHeloHostname()
      Sets the hostname sent in the SMTP EHLO or HELO command.

      The default value is an empty string, which causes Chilkat to use the local computer's hostname.

      Returns:
      the value of the HeloHostname property

    • setHeloHostname

      public void setHeloHostname​(String value)
      Sets the HeloHostname property; see getHeloHostname().
      Parameters:
      value - the new value (not null)

    • getHttpProxyAuthMethod

      public String getHttpProxyAuthMethod()
      Sets the authentication method used when the configured HTTP proxy requires credentials.

      Valid values are Basic and NTLM. Leave this property empty when the proxy does not require 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()
      Sets the optional Windows domain used for NTLM authentication with an HTTP proxy.

      This property is ignored for Basic proxy authentication and may be left empty when no NTLM domain is required.

      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()
      Sets the hostname or IP address of the HTTP proxy used for SMTP and POP3 connections.

      Leave this property empty to connect directly without an HTTP proxy.

      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()
      Sets the password used to authenticate with the configured HTTP proxy.

      This property is used together with getHttpProxyUsername() and, for NTLM authentication, may also be used with getHttpProxyDomain().

      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()
      Sets the TCP port of the HTTP proxy.

      Common proxy ports include 8080 and 3128. The value is used only when getHttpProxyHostname() is set.

      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()
      Sets the username used to authenticate with the configured HTTP proxy.

      This property 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)

    • getImmediateDelete

      public boolean getImmediateDelete()
      Determines whether pending POP3 deletion marks are committed automatically after a successful delete operation or full-message retrieval performed with keepOnServer = false.

      The default value is true. Chilkat sends DELE as each message is processed. After the complete operation succeeds, Chilkat sends QUIT, commits the deletions, and closes the POP3 session. The next POP3 method automatically reconnects and establishes a new session.

      When set to false, Chilkat sends DELE but leaves the session open and the deletions uncommitted. Call pop3EndSession() to send QUIT and commit them. Calling pop3Reset(), calling pop3EndSessionNoQuit(), or losing the POP3 connection before QUIT causes the server to forget the pending deletion marks.

      Header-only or partial-message retrieval never marks a message for deletion, regardless of this property or the value of keepOnServer.

      Returns:
      the value of the ImmediateDelete property

    • setImmediateDelete

      public void setImmediateDelete​(boolean value)
      Sets the ImmediateDelete property; see getImmediateDelete().
      Parameters:
      value - the new value

    • getIncludeRootCert

      public boolean getIncludeRootCert()
      Determines whether the root CA certificate is included in the S/MIME signature of a signed email.

      This property only applies when getEmbedCertChain() is true.

      Returns:
      the value of the IncludeRootCert property

    • setIncludeRootCert

      public void setIncludeRootCert​(boolean value)
      Sets the IncludeRootCert property; see getIncludeRootCert().
      Parameters:
      value - the new value

    • getIsPop3Connected

      public boolean getIsPop3Connected()
      Returns true if Chilkat believes the POP3 connection is still open.

      Accessing this property does not send any command to the POP3 server. If the server has disconnected but Chilkat has not yet attempted further communication, this property may still return true.

      To verify that the POP3 connection is actually alive, call pop3Noop().

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

    • getIsSmtpConnected

      public boolean getIsSmtpConnected()
      Returns true if Chilkat believes the SMTP connection is still open.

      Accessing this property does not communicate with the SMTP server. A lost connection may not be detected until the next SMTP command is sent.

      To verify that the SMTP connection is actually alive, call smtpNoop().

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

    • getLastSmtpStatus

      public int getLastSmtpStatus()
      Contains the SMTP failure status code returned by the server for the most recent SMTP operation.

      This property is nonzero only when Chilkat successfully connected, began an SMTP session, and then received a status code indicating failure. Such failures are generally reported by 4xx or 5xx replies.

      • 4xx — Temporary failure. Retrying later may succeed.
      • 5xx — Permanent failure. The request was rejected and usually requires a change before retrying.

      A value of 0 means that no SMTP failure status code was received. For example, the operation may have failed before an SMTP session was established. Use getSmtpFailReason() and LastErrorText for additional diagnostic information.

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

    • getLastSmtpStatusMsg

      public String getLastSmtpStatusMsg()
      Provides the text associated with the most recent SMTP reply received from the server.

      Use this property together with getLastSmtpStatus() when diagnosing an SMTP failure or interpreting a server-specific response.

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

    • getLogMailReceivedFilename

      public String getLogMailReceivedFilename()
      Specifies a local file path where Chilkat writes each message exactly as it was received from the POP3 server.

      This is useful for debugging problems involving MIME structure, encodings, attachments, or server behavior.

      Returns:
      the value of the LogMailReceivedFilename property

    • setLogMailReceivedFilename

      public void setLogMailReceivedFilename​(String value)
      Sets the LogMailReceivedFilename property; see getLogMailReceivedFilename().
      Parameters:
      value - the new value (not null)

    • getLogMailSentFilename

      public String getLogMailSentFilename()
      Specifies a local file path where Chilkat writes the exact MIME message sent to the SMTP server.

      This is useful for inspecting the final MIME produced by Chilkat.

      Returns:
      the value of the LogMailSentFilename property

    • setLogMailSentFilename

      public void setLogMailSentFilename​(String value)
      Sets the LogMailSentFilename property; see getLogMailSentFilename().
      Parameters:
      value - the new value (not null)

    • getMailHost

      public String getMailHost()
      Sets the POP3 server hostname or IP address.

      Do not include http:// or https://. The value should be a hostname such as pop.example.com or an IPv4/IPv6 address.

      Returns:
      the value of the MailHost property

    • setMailHost

      public void setMailHost​(String value)
      Sets the MailHost property; see getMailHost().
      Parameters:
      value - the new value (not null)

    • getMailPort

      public int getMailPort()
      Sets the POP3 server port number.

      The default value is 110.

      The standard POP3 ports and their associated MailMan property settings are described below.

      Port 995 — POP3 over Implicit SSL/TLS

      Uses implicit SSL/TLS, meaning the TLS connection is established immediately when the TCP connection is opened. 

      mailman.MailPort = 995;
 mailman.PopSsl = true;

      Port 110 — Standard Unencrypted POP3

      Uses a normal unencrypted POP3 connection. 

      mailman.MailPort = 110;
 mailman.PopSsl = false;
 mailman.Pop3Stls = false;
 mailman.Pop3StlsIfPossible = false;

      Port 110 — POP3 with Explicit TLS via STLS

      The connection begins unencrypted and is upgraded to TLS using the POP3 STLS command. 

      mailman.MailPort = 110;
 mailman.PopSsl = false;
 mailman.Pop3Stls = true;

      Port 110 — Opportunistic STLS

      Attempts to upgrade the connection to TLS using STLS if the POP3 server supports it. Otherwise, the connection remains unencrypted. 

      mailman.MailPort = 110;
 mailman.PopSsl = false;
 mailman.Pop3StlsIfPossible = true;

      Important: getPopSsl() and getPop3Stls() represent two different approaches to TLS security:

      • PopSsl = true means the connection begins as SSL/TLS from the very start (implicit TLS).
      • Pop3Stls = true means the connection begins unencrypted and is later upgraded to TLS using the POP3 STLS command (explicit TLS).

      These two approaches are mutually exclusive and should not both be enabled at the same time.

      Modern POP3 servers most commonly use either:

      • 995 with PopSsl = true, or
      • 110 with Pop3Stls = true.

      Returns:
      the value of the MailPort property

    • setMailPort

      public void setMailPort​(int value)
      Sets the MailPort property; see getMailPort().
      Parameters:
      value - the new value

    • getMaxCount

      public int getMaxCount()
      Limits the number of messages retrieved from the POP3 server. The following methods honor this property:

      The default value is 0, which means no limit.

      For FetchAll, a positive value selects the newest messages in the mailbox. For example, when MaxCount = 2, the two newest messages are retrieved and returned in normal mailbox order, with the older of the two first.

      Returns:
      the value of the MaxCount property

    • setMaxCount

      public void setMaxCount​(int value)
      Sets the MaxCount property; see getMaxCount().
      Parameters:
      value - the new value

    • getOAuth2AccessToken

      public String getOAuth2AccessToken()
      Sets the OAuth2 access token used for POP3 or SMTP XOAUTH2 authentication.

      When this property is set, Chilkat uses the AUTH XOAUTH2 authentication mechanism when it is supported by the server.

      For POP3 XOAUTH2 authentication: getPopPassword() should be left empty, or explicitly set to the empty string.

      For SMTP XOAUTH2 authentication: getSmtpPassword() should be left unset, or set to the empty string.

      The access token is sent as a bearer token during the AUTH XOAUTH2 authentication exchange.

      Returns:
      the value of the OAuth2AccessToken property

    • setOAuth2AccessToken

      public void setOAuth2AccessToken​(String value)
      Sets the OAuth2AccessToken property; see getOAuth2AccessToken().
      Parameters:
      value - the new value (not null)

    • getOpaqueSigning

      public boolean getOpaqueSigning()
      Controls the MIME format used for digitally signed email.

      When set to false, Chilkat creates a multipart/signed email. In this format, the original email content remains visible as a normal MIME body part, and the digital signature is included as a separate MIME part.

      The top-level MIME Content-Type header will look similar to: 

      Content-Type: multipart/signed;
     protocol="application/pkcs7-signature";
     micalg=sha-256;
     boundary="------------040808030405050402070604"

      This is commonly referred to as a detached signature because the signed content exists separately from the signature itself.

      When set to true, Chilkat creates an opaque signed email using PKCS#7 signed-data format. In this case, the original MIME content is encapsulated inside the PKCS#7 signature structure.

      The top-level MIME Content-Type header will look similar to: 

      Content-Type: application/pkcs7-mime;
     smime-type="signed-data";
     name="smime.p7m"; micalg=sha-256

      This format is historically known as opaque signing because the original message content is wrapped inside the PKCS#7 signed object and is not directly visible as ordinary MIME body parts.

      The default value is true.

      Returns:
      the value of the OpaqueSigning property

    • setOpaqueSigning

      public void setOpaqueSigning​(boolean value)
      Sets the OpaqueSigning property; see getOpaqueSigning().
      Parameters:
      value - the new value

    • getP7mEncryptAttachFilename

      public String getP7mEncryptAttachFilename()
      Sets the filename used in the Content-Disposition header when sending a PKCS#7 encrypted email.

      The default value is smime.p7m.

      Returns:
      the value of the P7mEncryptAttachFilename property

    • setP7mEncryptAttachFilename

      public void setP7mEncryptAttachFilename​(String value)
      Sets the P7mEncryptAttachFilename property; see getP7mEncryptAttachFilename().
      Parameters:
      value - the new value (not null)

    • getP7mSigAttachFilename

      public String getP7mSigAttachFilename()
      Sets the filename used in the Content-Disposition header when sending an opaque signed PKCS#7 email.

      The default value is smime.p7m.

      Returns:
      the value of the P7mSigAttachFilename property

    • setP7mSigAttachFilename

      public void setP7mSigAttachFilename​(String value)
      Sets the P7mSigAttachFilename property; see getP7mSigAttachFilename().
      Parameters:
      value - the new value (not null)

    • getP7sSigAttachFilename

      public String getP7sSigAttachFilename()
      Sets the filename used in the Content-Disposition header when sending a signed email with a detached PKCS#7 signature.

      The default value is smime.p7s.

      Returns:
      the value of the P7sSigAttachFilename property

    • setP7sSigAttachFilename

      public void setP7sSigAttachFilename​(String value)
      Sets the P7sSigAttachFilename property; see getP7sSigAttachFilename().
      Parameters:
      value - the new value (not null)

    • getPercentDoneScale

      public int getPercentDoneScale()
      This property is only valid in programming environments and languages that allow for event callbacks.

      Sets the value that represents 100% completion for PercentDone event callbacks.

      The default value is 100, meaning progress values range from 0 to 100. Setting this property to a larger value provides finer granularity. For example, setting PercentDoneScale = 1000 allows progress to be reported in tenths of a percent.

      For example, if PercentDoneScale = 1000, then a callback value of 453 represents 45.3% complete.

      The value is clamped to a minimum of 10 and a maximum of 100000.

      Returns:
      the value of the PercentDoneScale property

    • setPercentDoneScale

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

    • getPop3SPA

      public boolean getPop3SPA()
      Determines whether SPA, also known as NTLM authentication, is used for POP3.

      Set this property to true to use SPA authentication. No other programming changes are required.

      The default value is false.

      Note: If SPA/NTLM authentication fails, set Global.DefaultNtlmVersion = 1 and retry.

      Returns:
      the value of the Pop3SPA property

    • setPop3SPA

      public void setPop3SPA​(boolean value)
      Sets the Pop3SPA property; see getPop3SPA().
      Parameters:
      value - the new value

    • getPop3SessionId

      public int getPop3SessionId()
      Returns 0 when no POP3 session is active.

      Otherwise, returns a positive integer that increments each time a new POP3 session is established. This can be used to detect whether a new session has started.

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

    • getPop3SessionLog

      public String getPop3SessionLog()
      Provides the accumulated raw POP3 commands sent to the server and the raw responses received from the server.

      This property is read-only. To clear it, call clearPop3SessionLog().

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

    • getPop3SslServerCertVerified

      public boolean getPop3SslServerCertVerified()
      Indicates whether the POP3 server certificate chain was successfully verified during the most recent SSL/TLS POP3 connection.

      This property reports certificate-chain verification only. It does not report hostname matching or public key pinning. When either of those checks is required, a mismatch causes the connection itself to fail.

      This property is meaningful only after an SSL/TLS POP3 connection attempt.

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

    • getPop3Stls

      public boolean getPop3Stls()
      Determines whether Chilkat requires the POP3 connection to be upgraded to TLS using the STLS command.

      When set to true, Chilkat initially connects without encryption and then sends STLS before authenticating. The connection fails if the server does not support the required upgrade.

      getPopSsl() takes precedence. If implicit TLS is enabled, this property does not cause an additional explicit TLS upgrade.

      The default value is false. Use getPop3StlsIfPossible() when the upgrade should be attempted only when the server advertises support.

      Returns:
      the value of the Pop3Stls property

    • setPop3Stls

      public void setPop3Stls​(boolean value)
      Sets the Pop3Stls property; see getPop3Stls().
      Parameters:
      value - the new value

    • getPop3StlsIfPossible

      public boolean getPop3StlsIfPossible()
      Determines whether Chilkat attempts POP3 STLS when the server advertises support for it.

      If the server supports STLS, the connection is upgraded to TLS. Otherwise, the connection remains unencrypted.

      getPopSsl() takes precedence. If implicit TLS is enabled, no separate STLS upgrade is attempted. Use getPop3Stls() = true instead when encryption is required and the connection should fail if explicit TLS is unavailable.

      The default value is false.

      Returns:
      the value of the Pop3StlsIfPossible property

    • setPop3StlsIfPossible

      public void setPop3StlsIfPossible​(boolean value)
      Sets the Pop3StlsIfPossible property; see getPop3StlsIfPossible().
      Parameters:
      value - the new value

    • getPopPassword

      public String getPopPassword()
      Sets the POP3 password.

      On Windows, if getPop3SPA() is enabled, both getPopUsername() and PopPassword may be set to "default" to use the credentials of the current logged-on Windows user.

      Returns:
      the value of the PopPassword property

    • setPopPassword

      public void setPopPassword​(String value)
      Sets the PopPassword property; see getPopPassword().
      Parameters:
      value - the new value (not null)

    • getPopPasswordBase64

      public String getPopPasswordBase64()
      Sets the POP3 password as Base64-encoded data instead of plain text.

      MailMan decodes the Base64 value and uses the resulting bytes as the POP3 password. This property is useful when an application already stores or receives the password in Base64 form; Base64 encoding by itself does not provide encryption.

      Returns:
      the value of the PopPasswordBase64 property

    • setPopPasswordBase64

      public void setPopPasswordBase64​(String value)
      Sets the PopPasswordBase64 property; see getPopPasswordBase64().
      Parameters:
      value - the new value (not null)

    • getPopSsl

      public boolean getPopSsl()
      Determines whether implicit SSL/TLS is used when connecting to the POP3 server.

      When set to true, the TLS connection is established immediately when the TCP connection is opened. Implicit POP3 TLS commonly uses port 995.

      Implicit TLS takes precedence over explicit TLS. Therefore, when PopSsl = true, the settings in getPop3Stls() and getPop3StlsIfPossible() do not cause a separate STLS upgrade.

      The default value is false. When getAutoFix() is enabled, a standard POP3 port can cause Chilkat to select the appropriate TLS mode automatically before connecting.

      Returns:
      the value of the PopSsl property

    • setPopSsl

      public void setPopSsl​(boolean value)
      Sets the PopSsl property; see getPopSsl().
      Parameters:
      value - the new value

    • getPopUsername

      public String getPopUsername()
      Sets the POP3 login name.

      On Windows, if getPop3SPA() is enabled, both PopUsername and getPopPassword() may be set to "default" to use the credentials of the current logged-on Windows user.

      Returns:
      the value of the PopUsername property

    • setPopUsername

      public void setPopUsername​(String value)
      Sets the PopUsername property; see getPopUsername().
      Parameters:
      value - the new value (not null)

    • getPreferIpv6

      public boolean getPreferIpv6()
      Determines whether IPv6 is preferred over IPv4 when both are available for a hostname.

      The default value is false, which means IPv4 is preferred.

      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()
      Sets the maximum number of seconds to wait when the SMTP or POP3 server stops responding.

      The default value is 30 seconds.

      Returns:
      the value of the ReadTimeout property

    • setReadTimeout

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

    • getRequireHostnameMatch

      public boolean getRequireHostnameMatch()
      Determines whether the hostname used for the TLS connection must match a name in the server certificate's Subject Alternative Name (SAN) extension.

      The comparison is made against the SNI hostname sent in the TLS handshake. MailMan normally uses the configured server hostname. When connecting by IP address or through an alternate endpoint, set getSniHostname() to the expected DNS hostname.

      Hostname matching is enforced independently of getRequireSslCertVerify(). Therefore, it still occurs when certificate-chain verification is not required.

      Starting in v11.7.0, a wildcard SAN entry is matched as RFC 9525 (formerly RFC 6125) specifies. The wildcard must be the entire left-most label (*.example.com) and stands for exactly one label: *.example.com matches www.example.com, but not a.b.example.com and not the bare example.com. (Earlier versions matched the bare domain, and accepted a wildcard in any position.) A wildcard is not accepted directly under a top-level domain or a country-code second level such as co.uk, and never matches an IP address.

      The default value is false.

      Returns:
      the value of the RequireHostnameMatch property

    • setRequireHostnameMatch

      public void setRequireHostnameMatch​(boolean value)
      Sets the RequireHostnameMatch property; see getRequireHostnameMatch().
      Parameters:
      value - the new value

    • getRequireSslCertVerify

      public boolean getRequireSslCertVerify()
      Determines whether Chilkat requires the SMTP or POP3 server certificate chain to be successfully verified for an SSL/TLS connection.

      When set to true, Chilkat rejects the connection if the certificate is expired, is not yet valid, or its chain/signature cannot be verified to a trusted root.

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

      The default value is false. This property applies only to SSL/TLS connections.

      Returns:
      the value of the RequireSslCertVerify property

    • setRequireSslCertVerify

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

    • getResetDateOnLoad

      public boolean getResetDateOnLoad()
      Determines whether the email's Date header is reset to the current date and time when an email is loaded.

      This applies to methods such as LoadMbx, LoadEml, LoadMime, LoadXml, and LoadXmlString.

      The default value is false.

      Returns:
      the value of the ResetDateOnLoad property

    • setResetDateOnLoad

      public void setResetDateOnLoad​(boolean value)
      Sets the ResetDateOnLoad property; see getResetDateOnLoad().
      Parameters:
      value - the new value

    • getSendBufferSize

      public int getSendBufferSize()
      Sets the buffer size used by the underlying TCP/IP socket when sending data.

      The default value is 32767.

      Returns:
      the value of the SendBufferSize property

    • setSendBufferSize

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

    • getSizeLimit

      public int getSizeLimit()
      Sets the maximum message size, in bytes, for POP3 operations that can download one or more complete emails. It applies to any method capable of downloading a full email and does not restrict header-only or partial-body retrieval.

      The default value is 0, which means no size limit.

      For multi-message retrieval, a message larger than the limit is omitted from the result. No placeholder Email is added for the skipped message, and skipping an oversized message does not by itself cause the retrieval method to fail.

      Returns:
      the value of the SizeLimit property

    • setSizeLimit

      public void setSizeLimit​(int value)
      Sets the SizeLimit property; see getSizeLimit().
      Parameters:
      value - the new value

    • getSmtpAuthMethod

      public String getSmtpAuthMethod()
      Sets the SMTP authentication method to use.

      This property should usually be left empty so Chilkat can automatically choose the most secure method advertised by the SMTP server.

      If the server does not advertise authentication methods, or if a specific method must be forced, set this property to one of: NONE, LOGIN, PLAIN, CRAM-MD5, or NTLM.

      Note: If NTLM authentication fails, set Global.DefaultNtlmVersion = 1 and retry.

      Returns:
      the value of the SmtpAuthMethod property

    • setSmtpAuthMethod

      public void setSmtpAuthMethod​(String value)
      Sets the SmtpAuthMethod property; see getSmtpAuthMethod().
      Parameters:
      value - the new value (not null)

    • getSmtpFailReason

      public String getSmtpFailReason()
      Contains a keyword describing the result or failure reason for the last SMTP operation.

      Success: The method succeeded.

      Failed: A general failure occurred.

      NoValidRecipients: The SMTP server rejected all recipients.

      NoRecipients: No To, CC, or BCC recipients were provided.

      SomeBadRecipients: getAllOrNone() is true and some recipients were rejected.

      Aborted: The application aborted the operation.

      NoFrom: No FROM address was provided.

      FromFailure: The server rejected the MAIL FROM command.

      NoCredentials: Required credentials were not provided.

      AuthFailure: SMTP authentication failed.

      DataFailure: The server returned an error in response to DATA.

      NoSmtpHostname: No SMTP hostname or IP address was provided.

      StartTlsFailed: Failed to upgrade the connection using STARTTLS.

      ConnectFailed: Could not establish the TCP or TLS connection.

      GreetingError: The SMTP server returned an error in the initial greeting.

      ConnectionLost: The SMTP connection was lost during the operation.

      Timeout: A socket read or write timeout occurred.

      RenderFailed: The email could not be rendered for sending.

      NotUnlocked: UnlockBundle was not called on at least one MailMan instance.

      InternalFailure: An internal failure occurred and should be reported to Chilkat support.

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

    • getSmtpHost

      public String getSmtpHost()
      Sets the SMTP server hostname or IP address.

      Do not include http:// or https://. The value may be a hostname, IPv4 address, or IPv6 address.

      Returns:
      the value of the SmtpHost property

    • setSmtpHost

      public void setSmtpHost​(String value)
      Sets the SmtpHost property; see getSmtpHost().
      Parameters:
      value - the new value (not null)

    • getSmtpLoginDomain

      public String getSmtpLoginDomain()
      Sets the Windows domain to use when logging in to an SMTP server with NTLM authentication.

      Leave this property empty if no domain is required.

      Returns:
      the value of the SmtpLoginDomain property

    • setSmtpLoginDomain

      public void setSmtpLoginDomain​(String value)
      Sets the SmtpLoginDomain property; see getSmtpLoginDomain().
      Parameters:
      value - the new value (not null)

    • getSmtpMailFrom

      public String getSmtpMailFrom()
      Sets the SMTP envelope sender address used in the MAIL FROM command.

      This address receives bounce messages and identifies the originator of the SMTP transaction. It may differ from the From MIME header.

      If left empty, Chilkat uses the email address from the message's From header.

      SMTP servers may reject the envelope sender based on DNS, SPF, or other server policy checks.

      Returns:
      the value of the SmtpMailFrom property

    • setSmtpMailFrom

      public void setSmtpMailFrom​(String value)
      Sets the SmtpMailFrom property; see getSmtpMailFrom().
      Parameters:
      value - the new value (not null)

    • getSmtpPassword

      public String getSmtpPassword()
      Sets the password used for SMTP authentication.

      Chilkat supports SMTP authentication methods such as LOGIN, PLAIN, CRAM-MD5, and NTLM, and normally chooses the most secure available method automatically.

      If NTLM authentication is used, getSmtpUsername() and SmtpPassword may be set to the keyword "default" to use the current Windows logged-on credentials.

      Returns:
      the value of the SmtpPassword property

    • setSmtpPassword

      public void setSmtpPassword​(String value)
      Sets the SmtpPassword property; see getSmtpPassword().
      Parameters:
      value - the new value (not null)

    • getSmtpPipelining

      public boolean getSmtpPipelining()
      Determines whether SMTP pipelining is used when the server advertises support for it.

      The default value is true.

      Set this property to false to prevent SMTP pipelining. This is required when using getAllOrNone().

      Returns:
      the value of the SmtpPipelining property

    • setSmtpPipelining

      public void setSmtpPipelining​(boolean value)
      Sets the SmtpPipelining property; see getSmtpPipelining().
      Parameters:
      value - the new value

    • getSmtpPort

      public int getSmtpPort()
      Sets the SMTP server port.

      The default value is 25. If using implicit SSL/TLS with SmtpSsl = true, the common port is 465.

      Returns:
      the value of the SmtpPort property

    • setSmtpPort

      public void setSmtpPort​(int value)
      Sets the SmtpPort property; see getSmtpPort().
      Parameters:
      value - the new value

    • getSmtpSessionLog

      public String getSmtpSessionLog()
      Provides the accumulated raw SMTP commands sent to the server and raw responses received from the server.

      This property is read-only. To clear it, call clearSmtpSessionLog().

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

    • getSmtpSsl

      public boolean getSmtpSsl()
      Determines whether Chilkat uses implicit SSL/TLS when connecting to the SMTP server.

      When set to true, the TLS connection is established immediately when the TCP connection is opened. Implicit SMTP TLS commonly uses port 465.

      Implicit TLS takes precedence over explicit TLS. Therefore, when SmtpSsl = true, the settings in getStartTLS() and getStartTLSifPossible() do not cause a separate STARTTLS upgrade.

      The default value is false. When getAutoFix() is enabled, a standard SMTP port can cause Chilkat to select the appropriate TLS mode automatically before connecting.

      Returns:
      the value of the SmtpSsl property

    • setSmtpSsl

      public void setSmtpSsl​(boolean value)
      Sets the SmtpSsl property; see getSmtpSsl().
      Parameters:
      value - the new value

    • getSmtpSslServerCertVerified

      public boolean getSmtpSslServerCertVerified()
      Indicates whether the SMTP server certificate chain was successfully verified during the most recent SSL/TLS SMTP connection.

      This property reports certificate-chain verification only. It does not report hostname matching or public key pinning. When either of those checks is required, a mismatch causes the connection itself to fail.

      This property is meaningful only after an SSL/TLS SMTP connection attempt.

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

    • getSmtpUsername

      public String getSmtpUsername()
      Sets the username used for SMTP authentication.

      If getSmtpAuthMethod() is NTLM, SmtpUsername and getSmtpPassword() may be set to the keyword "default" to use the current Windows logged-on credentials.

      Returns:
      the value of the SmtpUsername property

    • setSmtpUsername

      public void setSmtpUsername​(String value)
      Sets the SmtpUsername property; see getSmtpUsername().
      Parameters:
      value - the new value (not null)

    • getSniHostname

      public String getSniHostname()
      Specifies the DNS hostname sent in the Server Name Indication (SNI) extension of the TLS handshake for SMTP and POP3 connections.

      Normally this property is left empty. In that case, MailMan uses getSmtpHost() for SMTP connections and getMailHost() for POP3 connections.

      Set this property when connecting by IP address or through an alternate endpoint while the server's TLS certificate and virtual-host configuration use a DNS hostname. The value is also used for certificate hostname comparison when getRequireHostnameMatch() is true.

      The default value is the empty string.

      Returns:
      the value of the SniHostname property

    • setSniHostname

      public void setSniHostname​(String value)
      Sets the SniHostname property; see getSniHostname().
      Parameters:
      value - the new value (not null)

    • getSoRcvBuf

      public int getSoRcvBuf()
      Sets the socket receive buffer size.

      The default value is 4194304.

      This property should normally be left unchanged. It may be increased if download performance is slow. Values should preferably be multiples of 4096.

      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 socket send buffer size.

      The default value is 262144.

      This property should normally be left unchanged. It may be increased if upload performance is slow. Testing values such as 512K or 1MB is reasonable. Values should preferably be multiples of 4096.

      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()
      Sets the SOCKS4 or SOCKS5 proxy hostname or IPv4 address.

      This property is used only when getSocksVersion() is set to 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()
      Sets the SOCKS5 proxy password, if authentication is required.

      SOCKS4 does not use passwords, so this property applies only to SOCKS5.

      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()
      Sets the SOCKS proxy port.

      The default value is 1080. This property applies only when getSocksVersion() is set to 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()
      Sets the SOCKS4 or SOCKS5 proxy username.

      This property is used only when getSocksVersion() is set to 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()
      Specifies whether a SOCKS proxy is used.
      • 0 — no SOCKS proxy is used. 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

    • getSslAllowedCiphers

      public String getSslAllowedCiphers()
      Sets the TLS cipher suites Chilkat is allowed to offer when establishing SSL/TLS connections.

      The default value is an empty string, meaning Chilkat may offer all implemented cipher suites. To restrict the allowed ciphers, set this property to a comma-separated list of cipher suite names, ordered by preference.

      The cipher suites supported by Chilkat are:

      TLS 1.3 Cipher Suites

      • TLS_AES_128_GCM_SHA256
      • TLS_CHACHA20_POLY1305_SHA256
      • TLS_AES_256_GCM_SHA384

      ChaCha20-Poly1305 Cipher Suites

      • TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
      • TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
      • TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256

      AES-GCM Cipher Suites

      • TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
      • TLS_DHE_RSA_WITH_AES_128_GCM_SHA256
      • TLS_RSA_WITH_AES_128_GCM_SHA256
      • TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
      • TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
      • TLS_DHE_RSA_WITH_AES_256_GCM_SHA384
      • TLS_RSA_WITH_AES_256_GCM_SHA384
      • TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384

      AES-128 CBC Cipher Suites

      • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
      • TLS_DHE_RSA_WITH_AES_128_CBC_SHA
      • TLS_RSA_WITH_AES_128_CBC_SHA
      • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
      • TLS_DHE_RSA_WITH_AES_128_CBC_SHA256
      • TLS_RSA_WITH_AES_128_CBC_SHA256
      • TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
      • TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256

      AES-256 CBC Cipher Suites

      • TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
      • TLS_DHE_RSA_WITH_AES_256_CBC_SHA
      • TLS_RSA_WITH_AES_256_CBC_SHA
      • TLS_DHE_RSA_WITH_AES_256_CBC_SHA256
      • TLS_RSA_WITH_AES_256_CBC_SHA256
      • TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
      • TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
      • TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384

      Important: The client offers a list of allowed cipher suites, but the server chooses the final cipher suite from that list.

      This property can also include special keywords:

      • rsa1024 — reject server certificates with RSA keys smaller than 1024 bits.
      • rsa2048 — reject server certificates with RSA keys smaller than 2048 bits.
      • secure-renegotiation — require secure renegotiation as defined by RFC 5746.
      • best-practices — use Chilkat's current best-practice cipher policy.

      The best-practices setting currently requires RSA server keys of at least 1024 bits, requires secure renegotiation, and disallows RC4, DES, and 3DES ciphers.

      Example:

      TLS_DHE_RSA_WITH_AES_256_CBC_SHA256, TLS_RSA_WITH_AES_256_CBC_SHA, rsa1024, secure-renegotiation
      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 SSL/TLS protocol version used for secure SMTP and POP3 connections.

      Possible values include:

      • 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 value is default, which allows Chilkat to choose the protocol dynamically based on the server's requirements.

      Choosing an exact protocol version can cause the connection to fail unless that exact version is negotiated. In most cases, using an or higher setting is preferable.

      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)

    • getStartTLS

      public boolean getStartTLS()
      Determines whether Chilkat requires SMTP STARTTLS.

      When set to true, Chilkat connects to the SMTP server normally and then sends the STARTTLS command to upgrade the connection to TLS before authenticating and sending email. The connection fails if the server does not support the required upgrade.

      getSmtpSsl() takes precedence. If implicit TLS is enabled, this property does not cause an additional explicit TLS upgrade.

      The default value is false. Use getStartTLSifPossible() when the upgrade should be attempted only when the server advertises support.

      This property applies to SMTP only, not POP3.

      Returns:
      the value of the StartTLS property

    • setStartTLS

      public void setStartTLS​(boolean value)
      Sets the StartTLS property; see getStartTLS().
      Parameters:
      value - the new value

    • getStartTLSifPossible

      public boolean getStartTLSifPossible()
      Determines whether Chilkat attempts SMTP STARTTLS when the server advertises support for it.

      If the server supports STARTTLS, the connection is upgraded to TLS. Otherwise, the connection remains unencrypted.

      getSmtpSsl() takes precedence. If implicit TLS is enabled, no separate STARTTLS upgrade is attempted. Use getStartTLS() = true instead when encryption is required and the connection should fail if explicit TLS is unavailable.

      The default value is true. This property applies to SMTP only, not POP3.

      Returns:
      the value of the StartTLSifPossible property

    • setStartTLSifPossible

      public void setStartTLSifPossible​(boolean value)
      Sets the StartTLSifPossible property; see getStartTLSifPossible().
      Parameters:
      value - the new value

    • getTlsCipherSuite

      public String getTlsCipherSuite()
      Contains the current or most recently negotiated TLS cipher suite.

      If no TLS connection has been established, or if the TLS connection attempt failed, this property is empty.

      Example value:

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

    • getTlsPinSet

      public String getTlsPinSet()
      Sets the expected Subject Public Key Info (SPKI) fingerprints for TLS public key pinning.

      During the TLS handshake, Chilkat compares the server certificate's public key fingerprint against this pin set. If none of the pins match, the connection fails.

      Pinning supplements normal certificate-chain verification; it does not replace it. A matching pin does not by itself make an expired or otherwise invalid certificate acceptable.

      The format is:

      hash_algorithm, encoding, SPKI_fingerprint_1, SPKI_fingerprint_2, ...

      Example with one SHA-256 Base64 pin:

      sha256, base64, lKg1SIqyhPSK19tlPbjl8s02yChsVTDklQpkMCHvsTE=

      Example with two SHA-256 Base64 pins:

      sha256, base64, 4t37LpnGmrMEAG8HEz9yIrnvJV2euVRwCLb9EH5WZyI=, 68b0G5iqMvWVWvUCjMuhLEyekM5729PadtnU5tdXZKs=

      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 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 current or most recently negotiated TLS protocol version.

      If no TLS connection has been established, or if the TLS connection attempt failed, this property is empty.

      Possible values include SSL 3.0, TLS 1.0, TLS 1.1, TLS 1.2, and TLS 1.3.

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

    • getUncommonOptions

      public String getUncommonOptions()
      Provides a comma-separated list of uncommon option keywords.

      This property defaults to an empty string and should normally remain empty.

      • ProtectFromVpn — introduced in v9.5.0.80. On Android, bypasses any installed or active VPN.
      • SmtpLoginAnsi — introduced in v9.5.0.97. Causes SMTP login and password strings containing non-ASCII characters to be sent using ANSI encoding instead of UTF-8. This restores the older Chilkat behavior for SMTP servers that expect ANSI credentials.

      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)

    • getUseApop

      public boolean getUseApop()
      Determines whether Chilkat automatically uses APOP authentication when the POP3 server supports it.

      The default value is false.

      Returns:
      the value of the UseApop property

    • setUseApop

      public void setUseApop​(boolean value)
      Sets the UseApop property; see getUseApop().
      Parameters:
      value - the new value

    • addPfxSourceBd

      public void addPfxSourceBd​(BinData bd, String password)
      Adds a PFX/PKCS#12 certificate store to the MailMan object's internal list of sources used for locating certificates and private keys.

      bd is a BinData object containing the bytes of a .pfx or .p12 file.

      The added PFX source is searched when Chilkat needs a certificate and private key for operations such as:

      • Decrypting S/MIME encrypted email
      • Creating digitally signed email

      Multiple PFX sources can be added by calling this method once for each PFX.

      On Windows, the registry-based Windows certificate stores are automatically searched when locating certificates and private keys. Therefore, if the required certificate and private key are already installed in the Windows certificate store, explicitly adding a PFX source is often unnecessary.

      On macOS, the Apple Keychain is also searched automatically. If the required certificate and private key are already available in the Apple Keychain, it is likewise unnecessary to explicitly add a PFX source.

      password specifies the password required to open the PFX.

      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 password)
      Adds a PFX/PKCS#12 file to the MailMan object's internal list of sources used for locating certificates and private keys. The pfxFilePath argument is the path to a .pfx or .p12 file.

      The added PFX source is searched when Chilkat needs a certificate and private key for operations such as:

      • Decrypting S/MIME encrypted email
      • Creating digitally signed email

      Multiple PFX sources can be added by calling this method once for each PFX.

      On Windows, the registry-based Windows certificate stores are automatically searched when locating certificates and private keys. Therefore, if the required certificate and private key are already installed in the Windows certificate store, explicitly adding a PFX source is often unnecessary.

      On macOS, the Apple Keychain is also searched automatically. If the required certificate and private key are already available in the Apple Keychain, it is likewise unnecessary to explicitly add a PFX source.

      The password argument specifies the password required to open the PFX.

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

    • checkMail

      public int checkMail()
      Returns the number of messages currently available in the POP3 mailbox. Returns -1 if an error occurs.

      If no POP3 session is active, Chilkat connects and authenticates automatically. After a successful call, the POP3 session remains open and can be reused by subsequent POP3 methods. Call pop3EndSession() or pop3EndSessionNoQuit() to end it.

      If this method fails, use verifyPopConnection() to test basic connectivity and verifyPopLogin() to test authentication.

      Returns:
      the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)

    • clearPop3SessionLog

      public void clearPop3SessionLog()
      Clears the current contents of the getPop3SessionLog() property.

    • clearSmtpSessionLog

      public void clearSmtpSessionLog()
      Clears the current contents of the getSmtpSessionLog() property.

    • closeSmtpConnection

      public void closeSmtpConnection()
      Explicitly closes the current SMTP connection. Before closing the socket connection, Chilkat sends the SMTP QUIT command to the server.

      Calling this method is optional in most applications. The MailMan object automatically opens an SMTP connection when an email-sending method is called and no connection is already open. The connection is then kept open so subsequent sends can reuse it. For example, if an application calls sendEmail(Email) ten times, the first call opens the SMTP connection, and the following calls send over the same connection.

      If an SMTP-related property changes, such as the hostname, username, password, port, or SSL/TLS settings, the existing connection is closed and a new connection is established the next time an email-sending method is called.

      The SMTP connection is also closed automatically when the MailMan object is destroyed.

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

    • deleteBundle

      public void deleteBundle​(EmailBundle emailBundle)
      Deletes POP3 messages by using the UIDLs stored in the X-UIDL headers of the Email objects in emailBundle. An email that does not contain an X-UIDL header is skipped.

      Chilkat processes the bundle and marks each located message with DELE. If a connection failure occurs before processing is complete, the POP3 session is lost and all uncommitted deletion marks are forgotten.

      If getImmediateDelete() is true, which is the default, Chilkat sends a single QUIT after the entire bundle has been processed. This commits all deletion marks and closes the POP3 session. If it is false, the marks remain pending until the application calls pop3EndSession().

      When making multiple deletion calls, it is usually more efficient to set ImmediateDelete to false, perform all deletion operations, and call Pop3EndSession once at the end.

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

    • deleteByMsgnum

      public void deleteByMsgnum​(int msgnum)
      Marks an email for deletion by its POP3 message number.

      Important: Message numbers are specific to a single POP3 session and can change from one session to the next. For example, if a mailbox contains ten messages, they are numbered 1 through 10. If message 1 is deleted and a new POP3 session is opened, the remaining messages are renumbered 1 through 9.

      A POP3 session must already be established before this method is called, either explicitly by calling pop3BeginSession() or implicitly by calling another method that opens the session. This method does not automatically begin a new session because doing so could change the message numbers and cause the application to delete a different message than intended.

      This method only marks the message for deletion. The message is not removed from the POP3 mailbox until the session is ended by calling pop3EndSession(), which sends the QUIT command.

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

    • deleteByUidl

      public void deleteByUidl​(String uidl)
      Marks the POP3 message identified by the UIDL in uidl for deletion. UIDLs are preferred over message numbers because they remain stable across sessions while the message remains in the mailbox.

      If getImmediateDelete() is true, which is the default, Chilkat sends QUIT, commits the deletion, and closes the session before returning. If it is false, the message is only marked with DELE; call pop3EndSession() to commit all pending deletions.

      pop3Reset() or pop3EndSessionNoQuit() cancels uncommitted deletion marks.

      If no POP3 session is active, Chilkat connects and authenticates automatically.

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

    • deleteEmail

      public void deleteEmail​(Email email)
      Deletes a POP3 message by using the UIDL stored in the X-UIDL header of the Email in email. If email does not contain an X-UIDL header, the method fails.

      If no POP3 session is active, Chilkat connects and authenticates automatically. The UIDL is used to locate the corresponding message in the current mailbox.

      If getImmediateDelete() is true, which is the default, Chilkat marks the message for deletion, sends QUIT to commit the deletion, and closes the POP3 session before returning. If it is false, the message is marked with DELE and the deletion remains pending until pop3EndSession() sends QUIT.

      pop3Reset() or pop3EndSessionNoQuit() cancels uncommitted deletion marks. Uncommitted marks are also forgotten if the POP3 connection is lost before QUIT is sent.

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

    • deleteUidlSet

      public void deleteUidlSet​(StringTable stUidls)
      Marks the POP3 messages whose UIDLs are listed in stUidls for deletion.

      Chilkat processes the UIDL set and sends DELE for each located message. If a connection failure occurs before processing is complete, the POP3 session is lost and all uncommitted deletion marks are forgotten.

      If getImmediateDelete() is true, which is the default, Chilkat sends a single QUIT after the entire set has been processed. This commits all deletion marks and closes the POP3 session. If it is false, the marks remain pending until the application calls pop3EndSession().

      When making multiple deletion calls, it is usually more efficient to set ImmediateDelete to false, perform all deletion operations, and call Pop3EndSession once at the end.

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

    • fetchAll

      public void fetchAll​(boolean keepOnServer, boolean headersOnly, int numBodyLines, EmailBundle bundle)
      Retrieves messages from the POP3 mailbox and appends them to the EmailBundle in bundle. Existing emails in bundle are preserved.

      If headersOnly is true, Chilkat retrieves the message headers and a partial body. numBodyLines specifies the number of body lines; a value of 0 retrieves the first body line. Attachments are not downloaded. If headersOnly is false, Chilkat retrieves the complete messages, including attachments.

      If keepOnServer is true, every retrieved message remains on the POP3 server, regardless of getImmediateDelete().

      If keepOnServer is false and complete messages are retrieved, Chilkat sends DELE for each message after it is downloaded. If ImmediateDelete = true, Chilkat sends QUIT only after the entire requested set has been downloaded successfully; this commits the deletions and closes the POP3 session. If ImmediateDelete = false, the deletion marks remain pending in the open session until the application calls pop3EndSession().

      If the POP3 connection is lost before QUIT, the session ends and the server forgets all uncommitted deletion marks. Chilkat automatically reconnects and establishes a new session when the next POP3 method is called.

      Header-only or partial retrieval never marks messages for deletion, regardless of keepOnServer or ImmediateDelete.

      getMaxCount() can limit the result to the newest messages. getSizeLimit() can omit oversized messages from full-message retrieval.

      If an error occurs while retrieving multiple messages, processing stops at the first failure. Messages that were successfully retrieved before the failure remain appended to the output EmailBundle; Chilkat does not remove those results or restore the bundle to its prior state.

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

    • fetchByUidl

      public void fetchByUidl​(String uidl, boolean headerOnly, int numBodyLines, Email email)
      Retrieves one message by UIDL and stores it in the Email in email. The message remains on the POP3 server.

      If headerOnly is true, Chilkat retrieves the headers and a partial body. numBodyLines specifies the number of body lines; a value of 0 retrieves the first body line. Attachments are not downloaded. If headerOnly is false, Chilkat retrieves the complete message, including attachments.

      If uidl is not found or the fetch otherwise fails, email is left unchanged.

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

    • fetchFull

      public void fetchFull​(Email partialEmail, Email fullEmail)
      Downloads the complete version of the header-only or partial Email in partialEmail and stores it in fullEmail. The full result includes the complete body and any attachments.

      partialEmail must retain the UIDL needed to locate the same message in the POP3 mailbox. The original POP3 session is not required; Chilkat connects and authenticates automatically when a session is not already active.

      If the UIDL no longer exists in the mailbox, or if the full message cannot be downloaded for another reason, the method fails and fullEmail remains unchanged.

      This method is useful when an application first retrieves headers or partial bodies and downloads the complete message only after the user selects it.

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

    • fetchMimeBd

      public void fetchMimeBd​(String uidl, BinData mimeData)
      Fetches an email from the POP3 server by UIDL and stores the raw MIME source bytes in mimeData.

      Chilkat clears the existing contents of mimeData before attempting the download. If the method succeeds, mimeData contains the downloaded MIME bytes. If it fails, mimeData remains empty.

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

    • fetchMimeByMsgnumBd

      public void fetchMimeByMsgnumBd​(int msgnum, BinData bd)
      Retrieves an email by POP3 message number and stores the raw MIME source bytes in bd.

      Chilkat clears the existing contents of bd before attempting the download. If the method succeeds, bd contains the downloaded MIME bytes. If it fails, bd remains empty.

      Important: Message numbers are specific to a single POP3 session and can change from one session to the next. For example, if a mailbox contains ten messages, they are numbered 1 through 10. If message 1 is deleted and a new POP3 session is opened, the remaining messages are renumbered 1 through 9.

      A POP3 session must already be established before this method is called, either explicitly by calling pop3BeginSession() or implicitly by calling another method that opens the session. This method does not automatically begin a new POP3 session because doing so could change the message numbers.

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

    • fetchOne

      public void fetchOne​(boolean headerOnly, int numBodyLines, int msgNum, Email email)
      Retrieves one message by POP3 message number and stores it in the Email in email. The first message has number 1. The message remains on the server.

      If headerOnly is true, Chilkat retrieves the headers and a partial body. numBodyLines specifies the number of body lines; a value of 0 retrieves the first body line. Attachments are not downloaded. If headerOnly is false, Chilkat retrieves the complete message, including attachments.

      If the message number is invalid or the fetch otherwise fails, email is left unchanged.

      POP3 message numbers are specific to the current mailbox state and can change between sessions. Use UIDLs when a message must be identified reliably across sessions.

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

    • fetchRange

      public void fetchRange​(boolean keepOnServer, boolean headersOnly, int numBodyLines, int startIndex, int endIndex, EmailBundle bundle)
      Retrieves a range of messages from the POP3 mailbox and appends them to the EmailBundle in bundle. Existing emails in bundle are preserved.

      startIndex and endIndex are zero-based, inclusive indexes in the server's current mailbox order. The messages are appended in increasing index order. If endIndex extends past the end of the mailbox, Chilkat stops at the final message. If startIndex is greater than endIndex, the method succeeds without appending any messages.

      If headersOnly is true, Chilkat retrieves the message headers and a partial body. numBodyLines specifies the number of body lines; a value of 0 retrieves the first body line. Attachments are not downloaded. If headersOnly is false, Chilkat retrieves the complete messages, including attachments.

      If keepOnServer is true, every retrieved message remains on the POP3 server, regardless of getImmediateDelete().

      If keepOnServer is false and complete messages are retrieved, Chilkat sends DELE for each message after it is downloaded. If ImmediateDelete = true, Chilkat sends QUIT only after the entire requested set has been downloaded successfully; this commits the deletions and closes the POP3 session. If ImmediateDelete = false, the deletion marks remain pending in the open session until the application calls pop3EndSession().

      If the POP3 connection is lost before QUIT, the session ends and the server forgets all uncommitted deletion marks. Chilkat automatically reconnects and establishes a new session when the next POP3 method is called.

      Header-only or partial retrieval never marks messages for deletion, regardless of keepOnServer or ImmediateDelete.

      If an error occurs while retrieving multiple messages, processing stops at the first failure. Messages that were successfully retrieved before the failure remain appended to the output EmailBundle; Chilkat does not remove those results or restore the bundle to its prior state.

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

    • fetchUidlSet

      public void fetchUidlSet​(StringTable uidls, boolean headersOnly, int numBodyLines, EmailBundle bundle)
      Retrieves the messages whose UIDLs are listed in uidls and appends them to the EmailBundle in bundle. Existing emails in bundle are preserved, and the retrieved messages remain on the POP3 server.

      UIDLs are processed in the order in which they occur in uidls. A duplicate UIDL causes the same message to be appended again. A UIDL that is not present in the mailbox is ignored and does not by itself cause the method to fail.

      If headersOnly is true, Chilkat retrieves the headers and a partial body. numBodyLines specifies the number of body lines; a value of 0 retrieves the first body line. Attachments are not downloaded. If headersOnly is false, Chilkat retrieves the complete messages, including attachments.

      If an error occurs while retrieving multiple messages, processing stops at the first failure. Messages that were successfully retrieved before the failure remain appended to the output EmailBundle; Chilkat does not remove those results or restore the bundle to its prior state.

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

    • fetchUidls

      public void fetchUidls​(StringTable uidls)
      Retrieves the UIDLs of the messages currently stored in the POP3 mailbox and stores them in uidls. The UIDLs are returned in the server's current mailbox order, with one entry for each message.

      A POP3 UIDL, or Unique ID Listing, is a persistent identifier assigned by the mail server. Unlike POP3 message numbers, which can change between sessions, a UIDL remains stable for as long as the message remains in the mailbox.

      If no POP3 session is active, Chilkat connects and authenticates automatically. After a successful call, the session remains open for reuse by subsequent POP3 methods.

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

    • getLastJsonData

      public void getLastJsonData​(JsonObject json)
      Copies into json any structured JSON details produced by the immediately preceding method call.

      Not every MailMan method produces JSON details. Call this method immediately after the operation of interest so the returned information corresponds to that operation.

      Parameters:
      json - the json argument (not null)

    • getMailboxCount

      public int getMailboxCount()
      Returns the number of emails currently available in the POP3 mailbox. Returns -1 if an error occurs.

      This method is functionally identical to checkMail().

      Returns:
      the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)

    • getMailboxInfoXml

      public String getMailboxInfoXml()
      Returns an XML document containing information about the messages currently stored in the POP3 mailbox.

      The XML includes the UIDL and size, in bytes, for each message in the mailbox. This is useful for scanning mailbox state without downloading the full messages.

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

    • getMailboxSize

      public long getMailboxSize()
      Returns the total combined size, in bytes, of all messages currently stored in the POP3 mailbox. This is also known as the POP3 maildrop size.

      If no POP3 session is active, Chilkat connects and authenticates automatically. After a successful call, the session remains open for reuse by subsequent POP3 methods.

      Returns -1 on failure.

      Returns:
      the result (see ChilkatObject.getLastMethodSuccess() where the description mentions failure)

    • getServerCert

      public void getServerCert​(boolean useSmtp, Cert cert)
      Gets the digital certificate presented by the SMTP or POP3 server for the current SSL/TLS connection and stores it in cert.

      If useSmtp is true, Chilkat returns the certificate for the SMTP connection. If useSmtp is false, Chilkat returns the certificate for the POP3 connection.

      This method applies only when the current connection uses SSL/TLS.

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

    • getSizeByUidl

      public int getSizeByUidl​(String uidl)
      Returns the size, in bytes, of the email on the POP3 server identified by uidl. The size includes the full message content, including attachments.

      Returns -1 if an error occurs.

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

    • isSmtpDsnCapable

      public boolean isSmtpDsnCapable()
      Contacts the SMTP server and determines whether it supports the DSN, or Delivery Status Notification, extension defined by RFC 3461.

      DSN support is used with properties such as getDsnEnvid(), getDsnNotify(), and getDsnRet(). Returns true if the SMTP server advertises DSN support, otherwise returns false.

      Returns:
      the result; this method never throws ChilkatException

    • loadMbxFile

      public void loadMbxFile​(String mbxPath, EmailBundle bundle)
      Loads emails from a .mbx mailbox file and stores them in bundle.

      If a filter has been configured, only the emails matching the filter are returned.

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

    • openSmtpConnection

      public void openSmtpConnection()
      Explicitly opens a connection to the SMTP server and authenticates if a username and password, OAuth2 token, or other applicable authentication settings have been provided.

      Calling this method is optional. Email-sending methods such as sendEmail(Email) automatically open and authenticate the SMTP connection when needed.

      This method is equivalent to calling smtpConnect() followed by smtpAuthenticate().

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

    • pop3Authenticate

      public void pop3Authenticate()
      Authenticates with the POP3 server using the current POP3 property settings, such as getPopUsername(), getPopPassword(), and any authentication-related options.

      This method should be called only after a successful call to pop3Connect(). The pop3BeginSession() method performs both steps and is equivalent to calling pop3Connect() followed by Pop3Authenticate.

      Calling this method is optional in most applications because POP3 methods that communicate with the server automatically connect and authenticate if no authenticated session is already open.

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

    • pop3BeginSession

      public void pop3BeginSession()
      Explicitly begins a POP3 session by connecting to the POP3 server and authenticating using the current POP3 property settings.

      Calling this method is optional. Any method that requires an established POP3 session automatically connects and logs in if a session is not already open.

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

    • pop3Connect

      public void pop3Connect()
      Explicitly connects to the POP3 server. If SSL/TLS is required by the current property settings, the secure TLS channel is established as part of this call. This method receives the server's initial greeting but does not authenticate.

      After Pop3Connect succeeds, call pop3Authenticate() to log in. The pop3BeginSession() method performs both steps and is equivalent to calling Pop3Connect followed by pop3Authenticate().

      Calling this method is optional in most applications because POP3 methods that communicate with the server automatically connect and authenticate if no authenticated session is already open. When finished with the POP3 server, call pop3EndSession() or pop3EndSessionNoQuit() to disconnect.

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

    • pop3EndSession

      public void pop3EndSession()
      Sends the POP3 QUIT command and closes the current POP3 connection.

      Any messages marked for deletion during the session are permanently deleted when the server accepts QUIT. After the session ends, getIsPop3Connected() is false and getPop3SessionId() returns 0.

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

    • pop3EndSessionNoQuit

      public void pop3EndSessionNoQuit()
      Closes the POP3 connection without sending the QUIT command.

      Pending deletion marks are not committed. Messages marked with DELE during the session remain in the mailbox after reconnecting.

      Use pop3EndSession() when pending deletions should be finalized.

      This method should always return true.

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

    • pop3Noop

      public void pop3Noop()
      Sends a POP3 NOOP command to the server.

      This can be useful for keeping a POP3 session alive or for verifying that the current POP3 connection is still open and functioning.

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

    • pop3Reset

      public void pop3Reset()
      Sends the POP3 RSET command to the server.

      Any messages marked for deletion during the current session are unmarked and remain in the mailbox. The POP3 session remains open after a successful reset.

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

    • pop3SendRawCommand

      public String pop3SendRawCommand​(String command, String charset)
      Sends a raw command to the POP3 server and returns the server's response.

      If command contains non-US-ASCII characters, charset specifies the character set used to encode the command before it is sent. Examples include utf-8, ansi, iso-8859-1, and Shift_JIS.

      This method is intended for advanced use, diagnostics, or issuing POP3 commands not directly exposed by higher-level MailMan methods.

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

    • quickSend

      public void quickSend​(String fromAddr, String toAddr, String subject, String body, String smtpServer)
      Sends a simple email to a single recipient without requiring the application to explicitly create an Email object.

      The fromAddr argument is the sender address, toAddr is the recipient address, subject is the message subject, body is the plain-text body, and smtpServer is the SMTP server hostname.

      This method is convenient for simple cases. For attachments, HTML email, CC/BCC recipients, alternate bodies, signing, encryption, or more control over headers and SMTP behavior, create an Email object and use sendEmail(Email) instead.

      Parameters:
      fromAddr - the fromAddr argument (not null)
      toAddr - the toAddr argument (not null)
      subject - the subject argument (not null)
      body - the body argument (not null)
      smtpServer - the smtpServer argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • renderToMime

      public String renderToMime​(Email email)
      Renders the Email in email as the MIME text that would be sent to the SMTP server, without actually sending the email.

      Rendering uses the current MailMan and Email settings and may include MIME formatting, header encoding, replacement-pattern substitution, digital signing, encryption, and other transformations required before transmission.

      This method does not modify email. Values generated as part of rendering are produced for the returned MIME and are not written back to the supplied Email. Repeated calls are not guaranteed to produce byte-for-byte identical MIME.

      By default, a Bcc header present in email is included in the rendered MIME. Add NoBccHeader to the Email object's UncommonOptions property to omit the Bcc header from the MIME.

      Conceptually, sendEmail(Email) performs this rendering step and then sends the resulting MIME.

      Note: If the MIME may contain 8-bit or binary data, use RenderToMimeBytes or renderToMimeBd(Email, BinData). Returning binary MIME as a string can corrupt bytes that are not valid text.

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

    • renderToMimeBd

      public void renderToMimeBd​(Email email, BinData renderedMime)
      Renders the Email in email as MIME bytes and appends the result to renderedMime.

      This method is the BinData version of RenderToMimeBytes. It is useful when the rendered MIME must be preserved as bytes, especially when it may contain 8-bit or binary MIME content.

      Rendering does not modify email. Values generated for the rendered MIME are not written back to the supplied Email.

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

    • renderToMimeSb

      public void renderToMimeSb​(Email email, StringBuilder renderedMime)
      Renders the Email in email as MIME text and appends the result to renderedMime.

      This method is the StringBuilder version of renderToMime(Email). Rendering does not modify email; values generated for the rendered MIME are not written back to the supplied Email.

      Note: If the MIME may contain 8-bit or binary content, use RenderToMimeBytes or renderToMimeBd(Email, BinData) instead. Returning binary MIME as text can corrupt data that is not valid text.

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

    • sendBundle

      public void sendBundle​(EmailBundle bundle)
      Sends each email in bundle. This is equivalent to calling sendEmail(Email) once for each email in the bundle.

      If an error occurs while sending one email, Chilkat continues attempting to send the remaining emails unless a fatal error occurs that requires the send operation to stop.

      Because it can be difficult or impossible to programmatically determine exactly which emails succeeded and which failed after a bundle send, applications that need detailed per-message status should loop through the bundle and call sendEmail(Email) for each message individually.

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

    • sendEmail

      public void sendEmail​(Email email)
      Sends a single email through the configured SMTP server.

      Chilkat automatically opens the SMTP connection when needed. After the email is sent, the connection remains open so a subsequent call to SendEmail or another email-sending method can reuse the same SMTP connection. If an SMTP-related property changes, such as getSmtpHost(), getSmtpUsername(), password, port, or SSL/TLS settings, Chilkat automatically closes the existing connection and establishes a new one using the updated settings on the next send.

      Important: Some SMTP servers do not complete final delivery processing until the SMTP connection is closed. In these cases, call closeSmtpConnection() after sending. Most SMTP servers process the message immediately, so explicitly closing the connection is usually not required.

      By default, a Bcc header in email is included in the MIME sent to the SMTP server. To prevent Bcc addresses from appearing in the MIME header, add NoBccHeader to the Email object's UncommonOptions property.

      After sending, additional information about the SMTP transaction may be available by calling getLastJsonData(JsonObject).

      If this method fails, examine getSmtpFailReason() and getLastSmtpStatus(). The latter is nonzero only when Chilkat established an SMTP session and received a failure status code from the server.

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

    • sendMime

      public void sendMime​(String fromAddr, String recipients, String mimeSource)
      Sends an email from caller-supplied MIME text. The MIME source in mimeSource is passed to the SMTP server as the message content.

      This method provides complete control over the MIME that is sent. It is useful when the application already has a fully formed MIME message, or when the MIME was created externally and should not be rebuilt from an Email object.

      The fromAddr argument is the SMTP reverse-path address used in the MAIL FROM command. This is where bounced email and non-delivery reports are normally delivered. It can be different from the From header in the MIME.

      recipients is a comma-separated list of plain email addresses used in SMTP RCPT TO commands. Do not include display names or formatted mailbox syntax; supply only addresses such as alice@example.com,bob@example.com.

      If this method fails, examine getSmtpFailReason() and getLastSmtpStatus(). The latter is nonzero only when Chilkat established an SMTP session and received a failure status code from the server.

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

    • sendMimeBd

      public void sendMimeBd​(String fromAddr, String recipients, BinData mimeData)
      Sends an email from caller-supplied MIME bytes contained in mimeData.

      This method is the BinData version of SendMimeBytes. It is useful when the MIME must be sent exactly as bytes, such as when it contains binary MIME content, 8bit encodings, or a DKIM/DomainKey signature where byte preservation matters.

      fromAddr is the SMTP reverse-path address used in the MAIL FROM command. recipients is a comma-separated list of plain email addresses used in SMTP RCPT TO commands. Do not include display names or formatted mailbox syntax in recipients.

      If this method fails, examine getSmtpFailReason() and getLastSmtpStatus(). The latter is nonzero only when Chilkat established an SMTP session and received a failure status code from the server.

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

    • setDecryptCert

      public void setDecryptCert​(Cert cert)
      Explicitly specifies the certificate to use when decrypting encrypted email.

      The certificate must correspond to the recipient certificate used to encrypt the message, and the associated private key must be available to Chilkat through the certificate itself, an added PFX source, an XML certificate vault, or the platform certificate store where applicable.

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

    • setDecryptCert2

      public void setDecryptCert2​(Cert cert, PrivateKey privateKey)
      Explicitly specifies both the certificate and its associated private key to use when decrypting S/MIME encrypted email.

      In most cases, it is simpler to call addPfxSourceFile(String, String) or AddPfxSourceData to provide the certificate and private key together in a PFX/PKCS#12 source. On Windows, if the certificate and private key are already installed in the default certificate store, no explicit setup may be needed because MailMan automatically searches the Windows certificate stores.

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

    • setPassword

      public void setPassword​(String protocolName, SecureString password)
      Sets the POP3 or SMTP password from a SecureString.

      The protocolName argument specifies which password is being set. Use pop3 to set the POP3 password, which is equivalent to setting the getPopPassword() property. Use smtp to set the SMTP password, which is equivalent to setting the getSmtpPassword() property.

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

    • setSslClientCert

      public void setSslClientCert​(Cert cert)
      Sets the client-side certificate to use for SSL/TLS connections.

      This is typically not required. Most SSL/TLS connections authenticate the server only, while the client remains unauthenticated at the TLS layer. Use this method only when the SMTP or POP3 server requires TLS client certificate authentication.

      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)
      Sets the client-side certificate to use for SSL/TLS connections, loading it from PEM data or from a PEM file.

      The pemDataOrFilename argument may contain PEM text or the path to a PEM file. The pemPassword argument supplies the password if the PEM private key is encrypted.

      TLS client certificates are typically required only when the server uses mutual TLS. Most SMTP and POP3 SSL/TLS connections do not require a client certificate.

      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 pfxPath, String pfxPassword)
      Sets the client-side certificate to use for SSL/TLS connections, loading it from a PFX/PKCS#12 file.

      The pfxPath argument is the path to the PFX file, and pfxPassword is the password required to open it.

      TLS client certificates are typically required only when the server uses mutual TLS. Most SMTP and POP3 SSL/TLS connections do not require a client certificate.

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

    • smtpAuthenticate

      public void smtpAuthenticate()
      Authenticates with the SMTP server using the current SMTP property settings, such as getSmtpUsername(), getSmtpPassword(), OAuth2 token settings, and other authentication-related options.

      This method should be called only after a successful call to smtpConnect(). The openSmtpConnection() method performs both steps and is equivalent to calling smtpConnect() followed by SmtpAuthenticate.

      Calling this method is optional in most applications because SMTP methods that communicate with the server, such as sendEmail(Email), automatically connect and authenticate if no authenticated SMTP connection is already open.

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

    • smtpConnect

      public void smtpConnect()
      Explicitly connects to the SMTP server. If SSL/TLS is required by the current property settings, the secure TLS channel is established as part of this call. This method receives the server's initial greeting but does not authenticate.

      After SmtpConnect succeeds, call smtpAuthenticate() to authenticate. The openSmtpConnection() method performs both steps and is equivalent to calling SmtpConnect followed by smtpAuthenticate().

      Calling this method is optional in most applications because SMTP methods that communicate with the server, such as sendEmail(Email), automatically connect and authenticate if no authenticated SMTP connection is already open.

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

    • smtpNoop

      public void smtpNoop()
      Sends an SMTP NOOP command to the server.

      This can be useful for testing whether the SMTP connection is working and still valid. If an SMTP connection is not already open, SmtpNoop automatically establishes the connection using the current SMTP property settings.

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

    • smtpReset

      public void smtpReset()
      Sends an SMTP RSET command to the server.

      The RSET command resets the server-side state of the current SMTP transaction so the connection can be used to begin a new mail transaction. This method is rarely needed. It would normally only be useful if a mail-sending method failed and left the SMTP connection open in a non-initial state, a situation that should generally not occur with the Chilkat MailMan object.

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

    • smtpSendRawCommand

      public String smtpSendRawCommand​(String command, String charset, boolean bEncodeBase64)
      Sends a raw command to the SMTP server and returns the server's response.

      If command contains non-US-ASCII characters, charset specifies the character set used to encode the command before it is sent. Examples include utf-8, ansi, iso-8859-1, and Shift_JIS.

      If bEncodeBase64 is true, the response is returned in Base64-encoded form. If bEncodeBase64 is false, the raw response text is returned.

      This method is intended for advanced use, diagnostics, or issuing SMTP commands not directly exposed by higher-level MailMan methods.

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

    • sshAuthenticatePk

      public void sshAuthenticatePk​(String sshLogin, SshKey privKey)
      Authenticates with the SSH server using public-key authentication after an SSH tunnel has been opened.

      The sshLogin argument is the SSH account name. The privKey argument is the SshKey containing the private key used for authentication. The matching public key must already be installed for the SSH account on the server.

      An SSH tunneling session begins by calling sshOpenTunnel(String, int) to connect to the SSH server, followed by either SshAuthenticatePk or sshAuthenticatePw(String, String) to authenticate.

      After the SSH tunnel is established and authenticated, MailMan's underlying SMTP or POP3 communication uses the SSH tunnel. No other programming changes are required beyond the initial tunnel setup calls.

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

    • sshAuthenticatePw

      public void sshAuthenticatePw​(String sshLogin, String sshPassword)
      Authenticates with the SSH server using an SSH username and password after an SSH tunnel has been opened.

      The sshLogin argument is the SSH account name, and sshPassword is the corresponding SSH password.

      An SSH tunneling session begins by calling sshOpenTunnel(String, int) to connect to the SSH server, followed by either SshAuthenticatePw or sshAuthenticatePk(String, SshKey) to authenticate.

      After the SSH tunnel is established and authenticated, MailMan's underlying SMTP or POP3 communication uses the SSH tunnel. No other programming changes are required beyond the initial tunnel setup calls.

      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 used for SMTP or POP3 communication.
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • sshOpenTunnel

      public void sshOpenTunnel​(String sshHostname, int sshPort)
      Connects to an SSH server and opens an SSH tunnel for MailMan's SMTP or POP3 connections.

      The sshHostname argument is the hostname or IP address of the SSH server. The sshPort argument is the SSH port, typically 22.

      An SSH tunneling session begins by calling SshOpenTunnel, followed by either sshAuthenticatePw(String, String) or sshAuthenticatePk(String, SshKey) to authenticate.

      After the SSH tunnel is established and authenticated, MailMan's underlying SMTP or POP3 communication uses the SSH tunnel. No other programming changes are required beyond the initial tunnel setup calls.

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

    • useCertVault

      public void useCertVault​(XmlCertVault vault)
      Provides an XML certificate vault to be searched for certificates and private keys when MailMan performs operations such as encryption, decryption, signing, or signature verification.

      Unlike PFX sources added with AddPfxSourceData, addPfxSourceBd(BinData, String), or addPfxSourceFile(String, String), only one XML certificate vault can be used at a time. If UseCertVault is called more than once, the most recent vault replaces the previously supplied vault.

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

    • useSsh

      public void useSsh​(Ssh ssh)
      Configures MailMan to use an existing SSH tunnel provided by the Ssh object in ssh for SMTP and POP3 connections.

      This method is similar to useSshTunnel(Socket), except the SSH tunnel is supplied in ssh rather than a Socket object.

      Sharing an existing SSH tunnel is useful when multiple objects need to communicate through the same SSH connection. SSH supports multiple logical channels within one tunnel, so SMTP and POP3 connections can exist simultaneously as separate SSH channels.

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

    • useSshTunnel

      public void useSshTunnel​(Socket tunnel)
      Configures MailMan to use an existing SSH tunnel provided by a Socket object for SMTP and POP3 connections.

      Sharing an existing SSH tunnel is useful when multiple objects need to communicate through the same SSH connection. SSH supports multiple logical channels within one tunnel, so SMTP and POP3 connections can exist simultaneously as separate SSH channels.

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

    • verifyPopConnection

      public boolean verifyPopConnection()
      Tests whether a TCP/IP connection can be established with the configured POP3 server.

      This method verifies connectivity only. It does not prove that POP3 authentication will succeed. Use verifyPopLogin() to test both connection and login.

      Returns true if the connection can be established, otherwise returns false.

      Returns:
      the result; this method never throws ChilkatException

    • verifyPopLogin

      public boolean verifyPopLogin()
      Tests whether Chilkat can connect to the configured POP3 server and successfully log in using the current POP3 authentication settings.

      Use this method to diagnose whether POP3 credentials and authentication settings are correct. If only the TCP/IP connection needs to be tested, use verifyPopConnection().

      Returns true if the connection and login succeed, otherwise returns false.

      Returns:
      the result; this method never throws ChilkatException

    • verifyRecips

      public void verifyRecips​(Email email, StringArray badAddrs)
      Begins the SMTP send process for email, sends the recipient addresses to the SMTP server, and then aborts before sending the message content. Recipient addresses rejected by the SMTP server are returned in badAddrs.

      This method can help identify addresses the SMTP server rejects during the SMTP RCPT TO stage. However, it cannot guarantee that all accepted addresses are valid. SMTP servers often accept addresses outside their own domains and only later discover delivery failures when relaying or delivering to the final destination.

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

    • verifySmtpConnection

      public boolean verifySmtpConnection()
      Tests whether a TCP/IP connection can be established with the configured SMTP server.

      This method verifies connectivity only. It does not prove that SMTP authentication will succeed. Use verifySmtpLogin() to test both connection and login.

      Returns true if the connection can be established, otherwise returns false.

      Returns:
      the result; this method never throws ChilkatException

    • verifySmtpLogin

      public boolean verifySmtpLogin()
      Tests whether Chilkat can connect to the configured SMTP server and successfully authenticate using the current SMTP authentication settings.

      Use this method to diagnose whether SMTP credentials and authentication settings are correct. If only the TCP/IP connection needs to be tested, use verifySmtpConnection().

      Returns true if the connection and login succeed, otherwise returns false.

      Returns:
      the result; this method never throws ChilkatException

    • 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