Chilkat.MailMan Class Overview
Chilkat.MailMan is the primary Chilkat class for sending email with SMTP and retrieving email with POP3. It also supports secure SMTP/POP3 connections, OAuth2 authentication, S/MIME signing and encryption, MIME rendering, POP3 mailbox inspection, proxies, SSH tunneling, DSN delivery notifications, and detailed SMTP/POP3 diagnostics.
What the Class Is Used For
Use Chilkat.MailMan when an application needs to send email through an SMTP server or retrieve email from a POP3 mailbox. The class is designed for applications that need practical control over authentication, TLS, message delivery, MIME formatting, POP3 download behavior, and troubleshooting.
Send Email with SMTP
Send simple messages, full Email objects, bundles,
distribution lists, or caller-supplied MIME.
Receive Email with POP3
Check mailbox counts, fetch full messages, fetch headers, retrieve UIDLs,
and delete messages from the server.
Secure Mail Workflows
Use SSL/TLS, STARTTLS, OAuth2/XOAUTH2, NTLM, client certificates, S/MIME
signing, and S/MIME decryption.
Diagnose Server Issues
Inspect SMTP/POP3 session logs, server status codes, connection failure reasons,
and exact MIME sent or received.
Scope note:
MailMan is for SMTP and POP3. For IMAP folder-based
mailbox access, use Chilkat.Imap.
Typical SMTP Sending Workflow
- Configure SMTP server settings such as SmtpHost, SmtpPort, SmtpUsername, SmtpPassword, and TLS options.
- Choose the secure connection style: SmtpSsl = true for implicit TLS, or StartTLS = true when STARTTLS is required.
- Create and populate a Chilkat.Email object, or provide already-rendered MIME using one of the SendMime* methods.
- Call SendEmail, SendBundle, SendMime, or QuickSend.
- Check LastErrorText, SmtpFailReason, LastSmtpStatus, or SmtpSessionLog if the send fails or behaves unexpectedly.
- Optionally call CloseSmtpConnection when finished, especially with servers that complete delivery processing only after the SMTP connection is closed.
Typical POP3 Receiving Workflow
- Configure POP3 settings such as MailHost, MailPort, PopUsername, PopPassword, and POP3 TLS options.
- Optionally call Pop3BeginSession. Most POP3 methods automatically connect and authenticate when needed.
- Use CheckMail or GetMailboxCount to determine how many messages are available.
- Use FetchUidls when stable message tracking is needed across POP3 sessions.
- Fetch messages with FetchAll, FetchRange, FetchOne, FetchByUidl, or FetchUidlSet.
- If deleting messages, prefer UIDL-based deletion when possible and understand that POP3 deletions are finalized when the session ends with QUIT.
- End the POP3 session with Pop3EndSession when needed.
Core Concepts
| Concept | Meaning | Important APIs |
|---|---|---|
| SMTP | The protocol used to send email. MailMan can send an Email object, a bundle, simple message fields, or caller-supplied MIME. | SendEmail, SendBundle, SendMime, QuickSend |
| POP3 | The protocol used to retrieve email from a mailbox. POP3 is message-oriented and does not expose the folder hierarchy available in IMAP. | CheckMail, FetchAll, FetchByUidl, FetchUidls |
| UIDL | A persistent POP3 identifier for a message. UIDLs are preferable to POP3 message numbers when tracking messages across sessions. | FetchUidls, FetchByUidl, DeleteByUidl, GetSizeByUidl |
| POP3 Message Number | A session-specific number assigned by the POP3 server. Message numbers can change between sessions after deletions or mailbox changes. | FetchOne, FetchMimeByMsgnum, DeleteByMsgnum |
| SMTP Envelope Sender | The address used in the SMTP MAIL FROM command. It may differ from the MIME From header and is where bounces are normally sent. | SmtpMailFrom, SendMime, SendMimeBytes |
| DSN | Delivery Status Notification support, used to request success, failure, or delay notifications from SMTP servers that advertise DSN capability. | DsnEnvid, DsnNotify, DsnRet, IsSmtpDsnCapable |
Major Feature Areas
| Area | What You Can Do | Representative Members |
|---|---|---|
| SMTP Sending | Send normal Email objects, MIME source, MIME bytes, message bundles, distribution lists, or simple one-off messages. | SendEmail, SendBundle, SendMime, SendMimeBytes, SendMimeBd, SendMimeToList, QuickSend |
| SMTP Connection Management | Open, authenticate, reuse, reset, test, and close SMTP connections. | OpenSmtpConnection, SmtpConnect, SmtpAuthenticate, SmtpNoop, SmtpReset, CloseSmtpConnection |
| POP3 Retrieval | Check mailbox counts, inspect mailbox size, retrieve UIDLs, fetch full messages, fetch headers, fetch ranges, and fetch raw MIME. | CheckMail, GetMailboxCount, GetMailboxInfoXml, FetchAll, FetchRange, FetchOne, FetchMime |
| POP3 Session Management | Explicitly begin, authenticate, test, reset, and end POP3 sessions when precise control is required. | Pop3BeginSession, Pop3Connect, Pop3Authenticate, Pop3Noop, Pop3Reset, Pop3EndSession |
| POP3 Deletion | Mark messages for deletion by message object, message number, UIDL, UIDL set, or bundle. | DeleteEmail, DeleteByUidl, DeleteByMsgnum, DeleteUidlSet, DeleteBundle, ImmediateDelete |
| MIME Rendering | Render an Email object to MIME text or exact MIME bytes without sending it. | RenderToMime, RenderToMimeBytes, RenderToMimeBd, RenderToMimeSb |
| Authentication | Authenticate using username/password, SecureString passwords, OAuth2/XOAUTH2, NTLM, LOGIN, PLAIN, CRAM-MD5, APOP, and POP3 SPA where supported. | SmtpAuthMethod, OAuth2AccessToken, SetPassword, UseApop, Pop3SPA |
| Secure Credential Resolution | Resolve passwords from Windows Credential Manager or Apple Keychain instead of embedding secrets directly in code. | EnableSecrets, PopPassword, SmtpPassword, HttpProxyPassword, SocksPassword |
| S/MIME Security | Sign email, embed certificate chains, choose opaque or detached signatures, decrypt encrypted email, and control signed/encrypted attachment names. | AutoUnwrapSecurity, OpaqueSigning, EmbedCertChain, IncludeRootCert, SetDecryptCert, SetDecryptCert2 |
| Certificate Sources | Provide certificate and private-key sources for signing, decryption, and TLS client certificate authentication. | AddPfxSourceFile, AddPfxSourceData, AddPfxSourceBd, UseCertVault, SetSslClientCert |
| Proxy and SSH Tunneling | Connect through HTTP proxies, SOCKS4/SOCKS5 proxies, or SSH tunnels. | HttpProxyHostname, SocksVersion, SshOpenTunnel, SshAuthenticatePw, UseSsh, UseSshTunnel |
| Diagnostics | Inspect protocol logs, status codes, bad recipients, connection failure reasons, and server certificates. | LastErrorText, SmtpFailReason, LastSmtpStatus, ConnectFailReason, SmtpSessionLog, Pop3SessionLog |
SMTP Configuration
| Purpose | Properties / Methods | Notes |
|---|---|---|
| Server and port | SmtpHost, SmtpPort | Use a hostname or IP address only. Do not include http:// or https://. |
| Username/password login | SmtpUsername, SmtpPassword, SmtpAuthMethod | Leave SmtpAuthMethod empty in most cases so Chilkat can choose the best method advertised by the server. |
| OAuth2 / XOAUTH2 | OAuth2AccessToken | When set, Chilkat uses XOAUTH2 authentication if supported by the SMTP server. |
| Envelope sender | SmtpMailFrom | Controls the SMTP MAIL FROM address. If empty, Chilkat uses the email object's From address. |
| All-or-none recipient acceptance | AllOrNone, SmtpPipelining | To require all recipients to be accepted before sending, set AllOrNone = true and SmtpPipelining = false. |
| Delivery Status Notification | DsnEnvid, DsnNotify, DsnRet, IsSmtpDsnCapable | DSN works only when the SMTP server advertises support for the DSN extension. |
POP3 Configuration
| Purpose | Properties / Methods | Notes |
|---|---|---|
| Server and port | MailHost, MailPort | MailPort defaults to 110. POP3 over implicit TLS commonly uses port 995. |
| Username/password login | PopUsername, PopPassword, PopPasswordBase64 | On Windows with POP3 SPA enabled, both username and password may be set to "default" to use the current Windows credentials. |
| OAuth2 / XOAUTH2 | OAuth2AccessToken | When using POP3 XOAUTH2, leave PopPassword empty. |
| Limit downloads | MaxCount, SizeLimit | Useful for large POP3 mailboxes or for downloading in manageable batches. |
| Session tracking | Pop3SessionId, IsPop3Connected | IsPop3Connected is the last-known state. Use Pop3Noop to verify that the connection is actually alive. |
SMTP and POP3 TLS Modes
| Protocol | Mode | Typical Port | Settings | Description |
|---|---|---|---|---|
| SMTP | Implicit SSL/TLS | 465 | SmtpSsl = true | TLS starts immediately when the TCP connection opens. |
| SMTP | STARTTLS required | 587 or 25 | StartTLS = true | The connection begins normally and must be upgraded to TLS before authentication and sending. |
| SMTP | STARTTLS if possible | 587 or 25 | StartTLSifPossible = true | Chilkat upgrades to TLS if the server advertises STARTTLS; otherwise the connection remains unencrypted. |
| POP3 | Implicit SSL/TLS | 995 | PopSsl = true | TLS starts immediately when connecting to the POP3 server. |
| POP3 | STLS required | 110 | Pop3Stls = true | The connection begins unencrypted and is upgraded to TLS using the POP3 STLS command. |
| POP3 | STLS if possible | 110 | Pop3StlsIfPossible = true | Chilkat upgrades to TLS when the server supports STLS; otherwise the connection remains unencrypted. |
Important:
For POP3, PopSsl and Pop3Stls
represent different TLS models. Do not enable both at the same time.
Message Retrieval Strategies
| Need | Recommended API | Why |
|---|---|---|
| Download everything | FetchAll | Retrieves all available POP3 messages into an EmailBundle. |
| Download in batches | MaxCount, FetchRange | Helps avoid downloading too much from a large POP3 mailbox at once. |
| Track what has already been downloaded | FetchUidls | UIDLs remain stable while messages remain in the mailbox, unlike message numbers. |
| Fetch a known message | FetchByUidl | UIDL-based retrieval is safer than message-number-based retrieval across sessions. |
| Initially load previews only | FetchAll, FetchRange, FetchOne with headers-only settings | Retrieves headers and optional body preview lines without downloading attachments. |
| Fetch the complete version of a partial message | FetchFull | Useful after a user selects a message from a header-only list. |
| Preserve exact MIME bytes | FetchMime, FetchMimeBd | Use raw MIME retrieval when exact message bytes matter. |
Sending Strategies
| Need | Recommended API | Notes |
|---|---|---|
| Send a normal Chilkat email object | SendEmail | Best general-purpose method for sending a fully configured Email object. |
| Send several email objects | SendBundle | Sends each message in an EmailBundle. For detailed per-message status, loop and call SendEmail yourself. |
| Send a simple plain-text message | QuickSend | Convenient for simple cases. Use Email + SendEmail for attachments, HTML, CC/BCC, signing, encryption, or custom headers. |
| Send already-built MIME text | SendMime | Use when the MIME is already prepared and should not be rebuilt from an Email object. |
| Send exact MIME bytes | SendMimeBytes, SendMimeBd | Recommended when MIME contains 8-bit content, binary data, or signatures where byte preservation matters. |
| Inspect MIME before sending | RenderToMime, RenderToMimeBytes, RenderToMimeBd | Useful for debugging the exact MIME that will be sent. |
S/MIME Signing, Encryption, and Decryption
MailMan works with Chilkat certificate objects, PFX/PKCS#12 sources, XML certificate vaults, Windows certificate stores, and Apple Keychain to locate certificates and private keys needed for secure email operations.
| Task | Relevant Members | Notes |
|---|---|---|
| Add a PFX certificate source | AddPfxSourceFile, AddPfxSourceData, AddPfxSourceBd | Adds a .pfx or .p12 source to search for certificates and private keys. |
| Use an XML certificate vault | UseCertVault | Adds a certificate vault as a source for signing, encryption, verification, or decryption. |
| Decrypt encrypted email | SetDecryptCert, SetDecryptCert2 | The corresponding private key must be available to Chilkat. |
| Automatically unwrap signed/encrypted email | AutoUnwrapSecurity | Enabled by default. Set to false if .p7m or .p7s content should remain as ordinary attachments. |
| Choose detached vs opaque signing | OpaqueSigning | false creates multipart/signed detached signatures. true creates opaque PKCS#7 signed-data. |
| Embed signing certificate chain | EmbedCertChain, IncludeRootCert | Controls whether the signing certificate chain and root certificate are embedded. |
Important:
Signature verification and S/MIME 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 for signature verification.
Diagnostics and Troubleshooting
Mail server problems often require inspecting both the high-level result and the exact SMTP or POP3 conversation. MailMan provides diagnostics for connection failures, authentication failures, rejected recipients, TLS negotiation, raw protocol transcripts, and MIME rendering.
| Diagnostic Need | Use |
|---|---|
| Detailed text for the last operation | LastErrorText |
| Numeric reason for the most recent connection attempt | ConnectFailReason |
| SMTP failure category | SmtpFailReason |
| Last SMTP status code and text | LastSmtpStatus, LastSmtpStatusMsg |
| Raw SMTP commands and responses | SmtpSessionLog, ClearSmtpSessionLog |
| Raw POP3 commands and responses | Pop3SessionLog, ClearPop3SessionLog |
| Exact MIME sent to the SMTP server | LogMailSentFilename |
| Exact MIME received from the POP3 server | LogMailReceivedFilename |
| SMTP connectivity and login tests | VerifySmtpConnection, VerifySmtpLogin |
| POP3 connectivity and login tests | VerifyPopConnection, VerifyPopLogin |
| Recipient verification | VerifyRecips |
| Additional structured details after some calls | GetLastJsonData |
SMTP status code guide:
2xx means success,
3xx means more information is required,
4xx means temporary failure, and
5xx means permanent failure.
Best Practices
| Recommendation | Reason |
|---|---|
| Use UIDLs instead of POP3 message numbers whenever possible. | POP3 message numbers are session-specific and can change. UIDLs are stable while the message remains in the mailbox. |
| Use RenderToMimeBytes or RenderToMimeBd when exact bytes matter. | MIME that contains binary or 8-bit content can be corrupted if treated as text. |
| Leave SmtpAuthMethod empty unless you must force a method. | Chilkat can normally choose the best authentication method advertised by the SMTP server. |
| Use StartTLS = true when encryption is mandatory. | StartTLSifPossible is opportunistic and allows the connection to remain unencrypted if STARTTLS is unavailable. |
| Disable SMTP pipelining when using all-or-none recipient behavior. | AllOrNone requires SmtpPipelining = false. |
| Use EnableSecrets for stored credentials. | It allows passwords to be resolved from Windows Credential Manager or Apple Keychain. |
| Use diagnostic verify methods before debugging higher-level send or fetch code. | VerifySmtpConnection, VerifySmtpLogin, VerifyPopConnection, and VerifyPopLogin isolate connection and authentication problems. |
| Log exact sent or received MIME when diagnosing formatting issues. | LogMailSentFilename and LogMailReceivedFilename preserve what was actually sent or received. |
Summary
Chilkat.MailMan is a full-featured SMTP and POP3 email class. It is used to send email, receive email, manage POP3 downloads and deletions, render and send MIME, use secure authentication, work with S/MIME, route traffic through proxies or SSH tunnels, and diagnose server communication in detail.
For server-side folder operations such as selecting IMAP folders, searching IMAP mailboxes, setting IMAP flags, or using IMAP IDLE, use the Chilkat.Imap class instead.