Package com.chilkatsoft.chilkat2

Class Email

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

Create, inspect, modify, secure, load, and save complete email messages.

Chilkat.Email represents a complete MIME email message, including headers, sender and recipient fields, subject, plain-text and HTML bodies, attachments, embedded HTML resources, attached messages, custom headers, and security-related information such as S/MIME signing and encryption status. It is the message object used throughout Chilkat when composing, parsing, modifying, saving, sending, receiving, or processing email.

Compose messages

Build email messages with sender, recipients, subject, text body, HTML body, reply-to fields, custom headers, and MIME structure.

Attachments and embedded content

Add, inspect, extract, remove, or save file attachments, embedded images, related HTML resources, and attached email messages.

Load and save MIME

Load email from MIME text, files, byte data, or strings, and save the message back to MIME, XML, files, or other supported forms.

Inspect received email

Read headers, addresses, dates, message IDs, body alternatives, attachments, encodings, and other fields from downloaded or parsed messages.

S/MIME security

Work with signed, encrypted, or signed-and-encrypted messages, including certificate-related information and security status.

Works with mail transports

Use Email objects with MailMan, Imap, EmailBundle, and related Chilkat classes for sending, receiving, downloading, and organizing mail.

Common pattern: Use Chilkat.Email to represent and manipulate the message itself. Use transport classes such as MailMan or Imap to send, receive, fetch, or manage messages on mail servers. After downloading or creating an email, use this class to inspect headers, modify content, handle attachments, save MIME, or prepare the message for further processing.

For an extended overview, see Email Class Overview.

</section>

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

    • Email

      public Email()
      Creates a new Email object.

  • Method Details

    • getBody

      public String getBody()
      Gets or sets the primary body of the email.

      When reading this property, an email containing both plain-text and HTML alternatives returns the HTML body. Use getHtmlBody() or getPlainTextBody() to retrieve a specific representation, and use hasHtmlBody() or hasPlainTextBody() to determine which representations are present.

      When setting this property, Chilkat inspects the supplied content to determine the body type. If the content is recognized as HTML, the HTML body is set. Otherwise, the plain-text body is set. If the email contains both plain-text and HTML alternatives, the corresponding alternative is replaced and the other alternative is left unchanged.

      For explicit control, use setTextBody(String, String), setHtmlBody(String), addPlainTextAlternativeBody(String), or addHtmlAlternativeBody(String).

      Returns:
      the value of the Body property

    • setBody

      public void setBody​(String value)
      Sets the Body property; see getBody().
      Parameters:
      value - the new value (not null)

    • getCharset

      public String getCharset()
      Represents the main charset of the email, such as utf-8, iso-8859-1, Shift_JIS, US-ASCII, etc. This property can be empty if there is no explicit charset, such as for emails with only US-ASCII.

      Setting this property causes Chilkat to use the new charset in HTML and plain-text bodies, where possible. This can include updating the HTML META tag in HTML bodies to agree with the charset specified in the email header and also the byte representation of the HTML body in the email.

      Chilkat stores text internally as Unicode. This property mainly controls how body text is converted to bytes and labeled when MIME is generated.

      Returns:
      the value of the Charset property

    • setCharset

      public void setCharset​(String value)
      Sets the Charset property; see getCharset().
      Parameters:
      value - the new value (not null)

    • getDecrypted

      public boolean getDecrypted()
      true if the email arrived encrypted and was successfully decrypted, otherwise false. This property is only meaningful when the getReceivedEncrypted() property is equal to true.

      Check getReceivedEncrypted() first. A value of false can mean either that the message was not encrypted or that decryption did not succeed.

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

    • getEmailDateStr

      public String getEmailDateStr()
      The date/time from the Date header in the UTC/GMT timezone in RFC822 string form.

      For example: Fri, 10 Jul 2026 20:15:30 GMT.

      Setting this property updates the email's Date header.

      Returns:
      the value of the EmailDateStr property

    • setEmailDateStr

      public void setEmailDateStr​(String value)
      Sets the EmailDateStr property; see getEmailDateStr().
      Parameters:
      value - the new value (not null)

    • getEncryptedBy

      public String getEncryptedBy()
      If the email was received encrypted, this contains the details of the certificate used for encryption.

      This property is meaningful only when getReceivedEncrypted() is true. To obtain a certificate object rather than descriptive text, use GetEncryptedByCert or lastDecryptCert(Cert).

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

    • getFileDistList

      public String getFileDistList()
      Set this property to send an email to a list of recipients stored in a plain text file. The file format is simple: one recipient per line, no comments allowed, blank lines are ignored. Setting this property is equivalent to adding a CKX-FileDistList header field to the email. MailMan treats header fields beginning with CKX- specially in that these fields are never transmitted with the email when sent. However, CKX fields are saved and restored when saving to XML or loading from XML (or MIME). When sending an email containing a CKX-FileDistList header field, MailMan will read the distribution list file and send the email to each recipient. Emails can be sent individually, or with BCC, 100 recipients at a time. (See the MailMan.SendIndividual property.)

      The distribution-list file is read when the message is sent, so the file must still exist and be accessible at that time. This feature is separate from the recipients stored in the normal To, Cc, and Bcc lists.

      Returns:
      the value of the FileDistList property

    • setFileDistList

      public void setFileDistList​(String value)
      Sets the FileDistList property; see getFileDistList().
      Parameters:
      value - the new value (not null)

    • getFrom

      public String getFrom()
      Contains the sender name and email address as they appear in the From header, such as John Smith <john.smith@mail.com>.

      If the sender identified by the Sender header field should differ from the visible From address, call addHeaderField(String, String) to set the Sender header field.

      From, getFromName(), and getFromAddress() are different views of the same MIME From header.

      Returns:
      the value of the From property

    • setFrom

      public void setFrom​(String value)
      Sets the From property; see getFrom().
      Parameters:
      value - the new value (not null)

    • getFromAddress

      public String getFromAddress()
      The email address of the sender.

      Changing this property updates the address portion of the MIME From header while preserving the sender name when possible.

      Returns:
      the value of the FromAddress property

    • setFromAddress

      public void setFromAddress​(String value)
      Sets the FromAddress property; see getFromAddress().
      Parameters:
      value - the new value (not null)

    • getFromName

      public String getFromName()
      The name of the sender.

      Changing this property updates the display-name portion of the MIME From header while preserving the email address.

      Returns:
      the value of the FromName property

    • setFromName

      public void setFromName​(String value)
      Sets the FromName property; see getFromName().
      Parameters:
      value - the new value (not null)

    • getHeader

      public String getHeader()
      The complete MIME header of the email.

      This is the header generated from the current in-memory email object. Modify individual fields through the corresponding properties or header methods rather than attempting to assign to this read-only property.

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

    • getLanguage

      public String getLanguage()
      Identifies the primary language group detected in the email subject and body text.
      • latin1 — English and Western European languages
      • central — Central European languages, such as Polish, Czech, and Hungarian
      • russian — Cyrillic languages
      • greek, turkish, hebrew, arabic, thai, or vietnamese
      • chinese, japanese, or korean
      • devanagari, bengali, gurmukhi, gujarati, oriya, tamil, telugu, kannada, malayalam, or sinhala
      • lao, tibetan, myanmar, or georgian
      • unknown

      Characters in address and other MIME header fields are not considered. The getSubject() header has the greatest influence on the result. For example, an email with Japanese text in the subject and Russian text in the body is classified as japanese.

      The classification is based on the Unicode blocks containing the characters found in the email.

      This is a character-based heuristic intended to help choose encodings. It is not taken from the MIME Content-Language header and should not be treated as formal language detection.

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

    • getLocalDateStr

      public String getLocalDateStr()
      The date/time found in the Date header field returned in the local timezone in RFC822 string form.

      For example: Fri, 10 Jul 2026 15:15:30 -0500.

      Setting this property updates the email's Date header. Use LocalDate when a native local date/time value is preferred.

      Returns:
      the value of the LocalDateStr property

    • setLocalDateStr

      public void setLocalDateStr​(String value)
      Sets the LocalDateStr property; see getLocalDateStr().
      Parameters:
      value - the new value (not null)

    • getMailer

      public String getMailer()
      Identifies the email software that sent the email.

      This corresponds to the MIME X-Mailer header, which is informational and may be absent or supplied by the sending application.

      Returns:
      the value of the Mailer property

    • setMailer

      public void setMailer​(String value)
      Sets the Mailer property; see getMailer().
      Parameters:
      value - the new value (not null)

    • getNumAlternatives

      public int getNumAlternatives()
      The number of body representations present in the email. A representation may be plain text, HTML, iCalendar, or another body format.

      A normal email with one body generally returns 1. A multipart/alternative email returns the number of alternatives contained in that enclosure. A newly created or cleared Email object also reports 1 for its default empty text body.

      An alternative is one of multiple representations of the same email body, such as plain text and HTML, within a multipart/alternative message.

      For example, an email containing plain-text and HTML alternatives, inline images, and an attachment may have a MIME structure similar to: 

      multipart/mixed
   multipart/alternative
     text/plain
     multipart/related
       text/html
       image/png
   application/pdf

      In this example, the text/plain part and the multipart/related part are alternatives. The multipart/related part contains the HTML body and an inline image, while the PDF is a separate attachment.

      Alternative indexes used by methods such as getAlternativeBody(int) are zero-based.

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

    • getNumAttachedMessages

      public int getNumAttachedMessages()
      The number of embedded emails represented by message/rfc822 MIME parts.

      Some mail clients attach a forwarded message as a complete nested email. These parts are counted separately from ordinary attachments and related items.

      Attached-message indexes are zero-based. Use getAttachedEmail(int, Email) to copy an embedded message into another Email object. The deprecated GetAttachedMessage method also returns an independent copy.

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

    • getNumAttachments

      public int getNumAttachments()
      The number of ordinary attachments contained in the email.

      Attachment indexes are zero-based. Related resources contained within a multipart/related enclosure are counted separately by getNumRelatedItems(), and embedded message/rfc822 emails are counted by getNumAttachedMessages().

      A MIME part outside a multipart/related enclosure may be classified as an attachment even when it does not explicitly contain Content-Disposition: attachment. MIME structure, content type, and disposition are considered together.

      Note: If an email is downloaded from an Imap server without attachment data, use the Imap method that reports attachment information for the server message. This property reports only the attachments actually present in the current Email object.

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

    • getNumBcc

      public int getNumBcc()
      The number of blind carbon-copy email recipients.

      Bcc recipient indexes are zero-based and can be inspected with getBcc(int), getBccAddr(int), and getBccName(int).

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

    • getNumCC

      public int getNumCC()
      The number of carbon-copy email recipients.

      Cc recipient indexes are zero-based and can be inspected with getCC(int), getCcAddr(int), and getCcName(int).

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

    • getNumDaysOld

      public int getNumDaysOld()
      Returns the number of days old from the current system date/time. The email's date is obtained from the Date header field. If the Date header field is missing, or invalid, then -9999 is returned. A negative number may be returned if the Date header field contains a future date/time. (However, -9999 represents an error condition.)

      The calculation uses the parsed Date header, not the time when the message was downloaded or loaded into the object.

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

    • getNumDigests

      public int getNumDigests()
      Returns the number of message/rfc822 parts contained within the multipart/digest enclosure. If no multipart/digest enclosure exists, then this property has the value of 0. The GetDigest method is called to get the Nth digest as an email object.

      Digest indexes are zero-based. Use getDigestEmail(int, Email) to retrieve an individual message from the digest.

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

    • getNumHeaderFields

      public int getNumHeaderFields()
      The number of header fields. When accessing a header field by index, the first header field is at index 0, and the last is at NumHeaderFields-1. (Chilkat indexing is always 0-based.)

      Repeated header fields are counted separately. Use getHeaderFieldName(int) and getHeaderFieldValue(int) to enumerate them by zero-based index.

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

    • getNumRelatedItems

      public int getNumRelatedItems()
      The number of related MIME items present in the email. Related items are resources, such as images or style sheets, contained with an HTML body in a multipart/related enclosure.

      Related-item indexes are zero-based. These parts are distinct from ordinary attachments and are commonly referenced by HTML using a cid: URL or a Content-Location value.

      Classification is based primarily on the MIME structure. An inline disposition or Content-ID alone does not necessarily make a part a related item if it is outside the relevant multipart/related enclosure.

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

    • getNumReplacePatterns

      public int getNumReplacePatterns()
      Returns the number of replacement patterns previously set by calling the setReplacePattern(String, String) method 1 or more times. If replacement patterns are set, the email bodies and header fields are modified by applying the search/replacement strings during the message sending process.

      Pattern indexes are zero-based. Replacement patterns are retained in the email object and applied later during supported mail-merge sending operations.

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

    • getNumReports

      public int getNumReports()
      Contains the number of report parts in a multipart/report email.

      A MIME part is counted as a report when its Content-Type is message/*, except for message/rfc822, or when its Content-Type is text/rfc822-headers. A message/rfc822 part is treated as an attached email and is counted by getNumAttachedMessages().

      Use getReport(int) to retrieve the body of each report part.

      Report indexes are zero-based. Use getReport(int) to retrieve the content of an individual report part.

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

    • getNumTo

      public int getNumTo()
      The number of direct email recipients.

      To-recipient indexes are zero-based and can be inspected with getTo(int), getToAddr(int), and getToName(int).

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

    • getOaepHash

      public String getOaepHash()
      Selects the hash algorithm used by OAEP padding when encrypting email with RSAES-OAEP. Valid values are sha1, sha256, sha384, and sha512. The default is sha256.

      This property is used only when getOaepPadding() is true.

      Returns:
      the value of the OaepHash property

    • setOaepHash

      public void setOaepHash​(String value)
      Sets the OaepHash property; see getOaepHash().
      Parameters:
      value - the new value (not null)

    • getOaepMgfHash

      public String getOaepMgfHash()
      Selects the mask-generation function (MGF) hash algorithm used by OAEP padding when encrypting email with RSAES-OAEP. Valid values are sha1, sha256, sha384, and sha512. The default is sha256.

      This property is used only when getOaepPadding() is true. Some recipients require the MGF hash to match getOaepHash().

      Returns:
      the value of the OaepMgfHash property

    • setOaepMgfHash

      public void setOaepMgfHash​(String value)
      Sets the OaepMgfHash property; see getOaepMgfHash().
      Parameters:
      value - the new value (not null)

    • getOaepPadding

      public boolean getOaepPadding()
      Selects the RSA encryption scheme when encrypting email. The default value is false, which selects RSAES_PKCS1-V1_5. When set to true, RSAES_OAEP is used.

      This affects the RSA key-encryption step used for S/MIME encryption; it does not change the symmetric content-encryption algorithm selected by getPkcs7CryptAlg().

      Returns:
      the value of the OaepPadding property

    • setOaepPadding

      public void setOaepPadding​(boolean value)
      Sets the OaepPadding property; see getOaepPadding().
      Parameters:
      value - the new value

    • getOverwriteExisting

      public boolean getOverwriteExisting()
      When true (the default) the methods to save email attachments and related items will overwrite files if they already exist. When false, the methods that save email attachments and related items will append a string of 4 characters to create a unique filename if a file already exists. The filename of the attachment (or related item) within the email object is updated and can be retrieved by the program to determine the actual file(s) created.

      This setting applies only when attachments or related items are written to the filesystem. When false and a name collision occurs during a save operation, Chilkat chooses a unique filename and updates the corresponding filename stored in the email object.

      Returns:
      the value of the OverwriteExisting property

    • setOverwriteExisting

      public void setOverwriteExisting​(boolean value)
      Sets the OverwriteExisting property; see getOverwriteExisting().
      Parameters:
      value - the new value

    • getPkcs7CryptAlg

      public String getPkcs7CryptAlg()
      When an email is sent encrypted (using PKCS#7 public-key encryption), this selects the underlying symmetric encryption algorithm. Possible values are: aes, aes-gcm, des, 3des, and rc2. The default value is aes.

      Note: The aes-gcm option was added in Chilkat v10.0.0

      This setting is used when S/MIME encryption is generated, typically after getSendEncrypted() is set to true and recipient encryption certificates have been supplied.

      Returns:
      the value of the Pkcs7CryptAlg property

    • setPkcs7CryptAlg

      public void setPkcs7CryptAlg​(String value)
      Sets the Pkcs7CryptAlg property; see getPkcs7CryptAlg().
      Parameters:
      value - the new value (not null)

    • getPkcs7KeyLength

      public int getPkcs7KeyLength()
      When the email is sent encrypted using PKCS#7 public-key encryption, this selects the key length of the underlying symmetric encryption algorithm. The default value is 128.

      The allowed values depend on getPkcs7CryptAlg():

      • For aes, use 128, 192, or 256.
      • For 3des, use 192.
      • For des, use 40.
      • For rc2, use 40, 56, 64, or 128.

      An unsupported algorithm and key-length combination causes the encryption operation to fail.

      Returns:
      the value of the Pkcs7KeyLength property

    • setPkcs7KeyLength

      public void setPkcs7KeyLength​(int value)
      Sets the Pkcs7KeyLength property; see getPkcs7KeyLength().
      Parameters:
      value - the new value

    • getPreferredCharset

      public String getPreferredCharset()
      Only applies when building an email with non-English characters where the charset is not explicitly set. The Chilkat email component will automatically choose a charset based on the languages found within an email (if the charset is not already specified within the MIME or explicitly specified by setting the getCharset() property). The default charset chosen for each language is:

      Chinese: gb2312
      Japanese: shift_JIS
      Korean: ks_c_5601-1987
      Thai: windows-874
      All others: iso-8859-*

      This allows for charsets such as iso-2022-jp to be chosen instead of the default. If the preferred charset does not apply to the situation, it is not used. For example, if the preferred charset is iso-2022-jp, but the email contains Greek characters, then the preferred charset is ignored.

      This is a preference, not a forced conversion. It is ignored when the message already specifies a charset or when the requested charset cannot represent the email text.

      Returns:
      the value of the PreferredCharset property

    • setPreferredCharset

      public void setPreferredCharset​(String value)
      Sets the PreferredCharset property; see getPreferredCharset().
      Parameters:
      value - the new value (not null)

    • getPrependHeaders

      public boolean getPrependHeaders()
      When true, header fields added via the addHeaderField(String, String) or addHeaderField2(String, String) methods are prepended to the top of the header as opposed to appended to the bottom. The default value is false.

      This affects header fields added after the property is set. It does not reorder fields that are already present.

      Returns:
      the value of the PrependHeaders property

    • setPrependHeaders

      public void setPrependHeaders​(boolean value)
      Sets the PrependHeaders property; see getPrependHeaders().
      Parameters:
      value - the new value

    • getReceivedEncrypted

      public boolean getReceivedEncrypted()
      true if this email was originally received with encryption, otherwise false.

      This records how the message was originally received. It remains useful after successful automatic decryption, when the visible body is already the decrypted content.

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

    • getReceivedSigned

      public boolean getReceivedSigned()
      true if this email was originally received with a digital signature, otherwise false.

      This records whether the original message contained one or more digital signatures. Use getSignaturesValid() to determine whether the signed content verified successfully.

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

    • getReplyTo

      public String getReplyTo()
      Sets the Reply-To header field to the specified email address such as john@example.com. The Reply-To header automatically defaults to the getFrom() email address. You would only set this property if you wish for the Reply-To email address to be different from the getFrom() address.

      There is usually only a single Reply-To email address. If multiple Reply-To addresses are needed, then set with a comma-separated list of email addresses such as john@example.com, mary@somewhere.com.

      This changes the MIME Reply-To header only; it does not change the SMTP envelope sender or the visible From header.

      Returns:
      the value of the ReplyTo property

    • setReplyTo

      public void setReplyTo​(String value)
      Sets the ReplyTo property; see getReplyTo().
      Parameters:
      value - the new value (not null)

    • getReturnReceipt

      public boolean getReturnReceipt()
      Set to true if you want the email to request a return-receipt when received by the recipient. The default value is false.

      Setting this property causes the Disposition-Notification-To email header to be added when the email is sent.

      A return receipt is only a request. The recipient's mail client or server may ignore it, and a receipt is not proof that the message was read by a person.

      Returns:
      the value of the ReturnReceipt property

    • setReturnReceipt

      public void setReturnReceipt​(boolean value)
      Sets the ReturnReceipt property; see getReturnReceipt().
      Parameters:
      value - the new value

    • getSendEncrypted

      public boolean getSendEncrypted()
      Set to true if this email should be sent encrypted. The default value is false.

      Encryption requires one or more recipient certificates, supplied with methods such as addEncryptCert(Cert) or setEncryptCert(Cert). Setting this property alone does not provide a certificate.

      Returns:
      the value of the SendEncrypted property

    • setSendEncrypted

      public void setSendEncrypted​(boolean value)
      Sets the SendEncrypted property; see getSendEncrypted().
      Parameters:
      value - the new value

    • getSendSigned

      public boolean getSendSigned()
      Set to true if this email should be sent with a digital signature. The default value is false.

      Signing requires a certificate with access to its private key, supplied with setSigningCert(Cert) or setSigningCert2(Cert, PrivateKey).

      Note: Please be aware of the Apple Mail bug explained in the webpage at the link below.

      Returns:
      the value of the SendSigned property

    • setSendSigned

      public void setSendSigned​(boolean value)
      Sets the SendSigned property; see getSendSigned().
      Parameters:
      value - the new value

    • getSignaturesValid

      public boolean getSignaturesValid()
      true if the email was received with one or more digital signatures, and if all the signatures were validated indicating that the email was not altered. Otherwise this property is set to false. (This property is only meaningful when the getReceivedSigned() property is equal to true.)

      This indicates cryptographic integrity of the signed content. Applications that also require certificate trust should separately examine the signer certificate and its chain.

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

    • getSignedBy

      public String getSignedBy()
      If the email was received digitally signed, this property contains the fields of the certificate's SubjectDN.

      For example: US, 94105, California, San Francisco, 100 Market Street, Northwind Research LLC, Engineering, Avery Morgan

      This is similar to a distinguished name (DN), but without the attribute names, such as C=, ST=, L=, O=, and CN=, preceding each value.

      This is intended for display or diagnostics. Use lastSignerCert(int, Cert) when the signer certificate itself is needed.

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

    • getSigningAlg

      public String getSigningAlg()
      Selects the signature algorithm to be used when sending signed (PKCS#7) email. The default value is PKCS1-v1_5. This can be set to RSASSA-PSS (or simply pss) to use the RSASSA-PSS signature scheme.

      Note: This property only applies when signing with an RSA private key. It does not apply for ECC or DSA private keys.

      This setting is used only for RSA signing. The selected scheme must also be supported by the private key provider.

      Returns:
      the value of the SigningAlg property

    • setSigningAlg

      public void setSigningAlg​(String value)
      Sets the SigningAlg property; see getSigningAlg().
      Parameters:
      value - the new value (not null)

    • getSigningHashAlg

      public String getSigningHashAlg()
      Selects the underlying hash algorithm used when sending signed (PKCS#7) email. Possible values are sha1, sha256, sha384, sha512, md5, and md2. The default is sha1.

      This property controls the message-digest algorithm placed in the signature. It is used only when a signed message is generated.

      Returns:
      the value of the SigningHashAlg property

    • setSigningHashAlg

      public void setSigningHashAlg​(String value)
      Sets the SigningHashAlg property; see getSigningHashAlg().
      Parameters:
      value - the new value (not null)

    • getSize

      public int getSize()
      The size in bytes of the email, including all parts and attachments.

      Note: This property is only valid if the full email was downloaded. If only the header was downloaded, then this property will contain the size of just the header.

      This value describes the email data currently present in the object. It should not be used as the server-reported full message size when only a partial message was downloaded.

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

    • getSubject

      public String getSubject()
      The email subject.

      This property reads or writes the MIME Subject header. Chilkat performs the required MIME header encoding when the subject contains non-ASCII characters.

      Returns:
      the value of the Subject property

    • setSubject

      public void setSubject​(String value)
      Sets the Subject property; see getSubject().
      Parameters:
      value - the new value (not null)

    • getUidl

      public String getUidl()
      Contains the unique message identifier assigned by a POP3 server. The value is also represented by the X-UIDL header field.

      Important: UIDLs are specific to POP3. IMAP uses UIDs instead. An email downloaded through Chilkat.Imap stores its IMAP identifier in the ckx-imap-uid header. The ckx-imap-isUid header contains YES when that value is an IMAP UID, or NO when it is a mailbox sequence number.

      A UIDL identifies a POP3 message within the server's mailbox and is normally used to avoid downloading the same message repeatedly.

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

    • getUncommonOptions

      public String getUncommonOptions()
      This is a catch-all property to be used for uncommon needs. This property defaults to the empty string, and should typically remain empty.
      • NoBccHeader - (added in v11.0.0) Do not add the Bcc MIME header for BCC email addresses. Note: The NoBccHeader keyword must be present before calling addBcc(String, String) or addMultipleBcc(String)
      • NO_FORMAT_FLOWED - Don't automatically add format=flowed to any Content-Type header.

      Leave this property empty unless a documented compatibility option is specifically required. Unrecognized keywords should not be assumed to have any effect.

      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)

    • getUnpackUseRelPaths

      public boolean getUnpackUseRelPaths()
      Applies to the unpackHtml(String, String, String) method. When true, relative paths are used within the HTML for the links to the related files (images and style sheets) that were unpacked to the filesystem. Otherwise absolute paths are used. The default value is true.

      Relative paths are usually preferable when the unpacked HTML directory will be moved or deployed as a unit. Absolute paths can be useful for immediate local viewing.

      Returns:
      the value of the UnpackUseRelPaths property

    • setUnpackUseRelPaths

      public void setUnpackUseRelPaths​(boolean value)
      Sets the UnpackUseRelPaths property; see getUnpackUseRelPaths().
      Parameters:
      value - the new value

    • addAttachmentBd

      public void addAttachmentBd​(String filename, BinData binData, String contentType)
      Adds an attachment using the contents of a BinData object. If contentType is empty, then the Content-Type will be inferred from filename extension.

      filename is the filename stored in MIME, not a filesystem path. The bytes are taken from binData.

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

    • addAttachmentHeader

      public void addAttachmentHeader​(int index, String fieldName, String fieldValue)
      Adds or replaces a MIME header field in one of the email attachments. If the header field does not exist, it is added. Otherwise it is replaced.

      Indexing: index is zero-based and must identify an existing attachment. This changes the attachment MIME header in the current email object; it does not modify the original source file.

      Parameters:
      index - the index argument
      fieldName - the fieldName argument (not null)
      fieldValue - the fieldValue argument (not null)

    • addBcc

      public void addBcc​(String friendlyName, String emailAddress)
      Adds a recipient to the blind carbon-copy (BCC) list. emailAddress is required; friendlyName is optional. Call this method separately for each BCC recipient.

      Note: Before v11.0.0, BCC addresses are not added to the MIME header. After v11.0.0, BCC addresses are included in the MIME header. Most email servers remove the BCC header before delivering the message to regular recipients. The NoBccHeader keyword can be used in getUncommonOptions() to prevent BCC email addresses in the MIME passed to the SMTP server. If your application specifies NoBccHeader, do so before adding BCC addresses.

      The recipient is added to the in-memory message only. The message is not transmitted until it is passed to a sending method of MailMan.

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

    • addCC

      public void addCC​(String friendlyName, String emailAddress)
      Adds a recipient to the carbon-copy list. emailAddress is required, but friendlyName may be empty.

      To add multiple CC recipients, call this method once per recipient.

      The recipient is added to the in-memory message only. Use getNumCC() and the Cc getter methods to inspect the resulting list.

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

    • addEncryptCert

      public void addEncryptCert​(Cert cert)
      Allows for certificates to be explicitly specified for sending encrypted email to one or more recipients. Call this method once per certificate to be used. The clearEncryptCerts() method may be called to clear the list of explicitly-specified certificates.

      Note: It is possible to send encrypted email without explicitly specifying the certificates. On Windows, the registry-based Current-User and Local-Machine certificate stores are automatically searched for certificates matching each recipient in the To, CC, and BCC lists. On macOS, the Keychain is automatically searched for matching recipient certificates.

      Note: The setEncryptCert(Cert) method is equivalent to calling clearEncryptCerts() followed by AddEncryptCert.

      Use this method when encrypting for multiple recipients: add each recipient certificate separately. For a single explicitly selected certificate, setEncryptCert(Cert) may be simpler.

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

    • addFileAttachment

      public String addFileAttachment​(String path)
      Adds a file as an attachment to the email. Returns the MIME Content-Type of the attachment, which is inferred based on the filename extension.

      path is a local filesystem path. The file is read and incorporated into the current email object, and the attachment filename placed in MIME is derived from path.

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

    • addFileAttachment2

      public void addFileAttachment2​(String path, String contentType)
      Same as addFileAttachment(String), but the content type can be explicitly specified.

      Use this form when filename-based MIME type inference is unsuitable. contentType should be a MIME media type such as application/octet-stream.

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

    • addHeaderField

      public void addHeaderField​(String fieldName, String fieldValue)
      Any standard or non-standard (custom) header field can be added to the email with this method. One interesting feature is that all header fields whose name begins with CKX- will not be included in the header when an email is sent. These fields will be included when saved to or loaded from XML. This makes it easy to include persistent meta-data with an email which your programs can use in any way it chooses.

      Important: This method will replace an already-existing header field. To allow for adding duplicate header fields, call addHeaderField2(String, String) (see below).

      This changes the MIME header stored in the current email object. It does not change the SMTP envelope, except where another component explicitly interprets a particular header.

      Parameters:
      fieldName - the fieldName argument (not null)
      fieldValue - the fieldValue argument (not null)

    • addHeaderField2

      public void addHeaderField2​(String fieldName, String fieldValue)
      This method is the same as addHeaderField(String, String), except that if the header field already exists, it is not replaced. A duplicate header will be added.

      Use this method for headers that may legally occur more than once, such as Received. For a single-valued field that should be replaced, use addHeaderField(String, String).

      Parameters:
      fieldName - the fieldName argument (not null)
      fieldValue - the fieldValue argument (not null)

    • addHtmlAlternativeBody

      public void addHtmlAlternativeBody​(String body)
      Adds or replaces the HTML body representation of the email.

      If no HTML alternative exists, one is added. If an HTML alternative already exists, it is replaced rather than duplicated. Repeated calls therefore leave at most one HTML alternative.

      When paired with addPlainTextAlternativeBody(String), Chilkat creates a multipart/alternative body so mail clients can choose the representation they support. Use setHtmlBody(String) when a multipart alternative is not needed.

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

    • addMultipleBcc

      public void addMultipleBcc​(String commaSeparatedAddresses)
      Parses the mailbox list in commaSeparatedAddresses and appends the results to the blind carbon-copy (Bcc) recipient list.

      Recipients may be separated by commas or semicolons. Each item may be a bare address or a mailbox with a display name. Quoted display names may contain commas.

      Empty items are ignored. Duplicate addresses are retained.

      Note: Before v11.0.0, BCC addresses were not added to the MIME header. Starting in v11.0.0, BCC addresses are included in the MIME header. Most email servers remove the Bcc header before delivering the message to regular recipients. To omit BCC addresses from generated MIME, place the NoBccHeader keyword in getUncommonOptions() before adding BCC recipients.

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

    • addMultipleCC

      public void addMultipleCC​(String commaSeparatedAddresses)
      Parses the mailbox list in commaSeparatedAddresses and appends the results to the carbon-copy (Cc) recipient list.

      Recipients may be separated by commas or semicolons. Each item may be a bare address or a mailbox with a display name. Quoted display names may contain commas.

      Empty items are ignored. Duplicate addresses are retained.

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

    • addMultipleTo

      public void addMultipleTo​(String commaSeparatedAddresses)
      Parses the mailbox list in commaSeparatedAddresses and appends the results to the direct-recipient (To) list.

      Recipients may be separated by commas or semicolons. Each item may be a bare address or a mailbox with a display name. Quoted display names may contain commas.

      Empty items are ignored. Duplicate addresses are retained.

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

    • addPfxSourceBd

      public void addPfxSourceBd​(BinData bd, String password)
      Adds the PFX data in bd to the list of certificate and private-key sources used during decryption or signing. password contains the PFX password.

      Call this method once for each additional PFX source.

      The PFX data becomes a lookup source for subsequent cryptographic operations by this object. Adding it does not immediately decrypt or sign the message.

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

    • addPfxSourceFile

      public void addPfxSourceFile​(String pfxFilePath, String pfxPassword)
      Adds the PFX file specified by pfxFilePath to the internal list of certificate and private-key sources used during decryption. pfxPassword contains the PFX password.

      Call this method once for each additional PFX file. On Windows, Chilkat automatically searches the system certificate stores. On macOS, Chilkat automatically searches the Keychain. Therefore, explicitly adding a PFX source is often unnecessary when the required certificate and private key are already installed.

      The PFX file becomes a certificate source for later operations performed by this email object. The file must be readable when this method is called.

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

    • addPlainTextAlternativeBody

      public void addPlainTextAlternativeBody​(String body)
      Adds or replaces the plain-text body representation of the email.

      If no plain-text alternative exists, one is added. If a plain-text alternative already exists, it is replaced rather than duplicated. Repeated calls therefore leave at most one plain-text alternative.

      When paired with addHtmlAlternativeBody(String), Chilkat creates a multipart/alternative body so text-only clients have a suitable representation. Use setTextBody(String, String) when a multipart alternative is not needed.

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

    • addRelatedBd

      public String addRelatedBd​(String filename, BinData binData)
      Adds a related item using the contents of a BinData object. Returns the Content-ID for the newly added related item.

      The returned Content-ID can be used in the HTML body as cid:returnedContentId.

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

    • addRelatedBd2

      public void addRelatedBd2​(BinData binData, String fileNameInHtml)
      Adds a related item using the binary data in binData.

      fileNameInHtml specifies the filename, path, or URL used by the corresponding HTML reference, such as an img element's src attribute.

      This form is useful when the HTML already contains a filename, URL, or path reference that Chilkat should associate with the new related MIME part.

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

    • addRelatedFile

      public String addRelatedFile​(String path)
      Adds the contents of the local file in path as a related MIME resource and returns the generated Content-ID.

      The returned value is the bare Content-ID. It does not include angle brackets or the cid: prefix. For example, if the method returns CID-123@example, the HTML reference is cid:CID-123@example.

      This method does not modify the HTML body. The application must add or update the corresponding cid: reference itself.

      The file becomes a related MIME resource rather than an ordinary attachment.

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

    • addRelatedFile2

      public void addRelatedFile2​(String filenameOnDisk, String filenameInHtml)
      Adds the local file in filenameOnDisk as a related MIME resource addressed by Content-Location rather than Content-ID.

      filenameInHtml becomes the related item's MIME filename and Content-Location value. It should match the filename, path, or URL already used by the corresponding HTML reference, such as an img element's src attribute.

      This method does not generate a Content-ID and does not modify the HTML body. The HTML must already refer to filenameInHtml.

      Note: Outlook.com may fail to display embedded images when filenameInHtml contains a path. For best compatibility, use only a filename when targeting Outlook.com.

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

    • addRelatedHeader

      public void addRelatedHeader​(int index, String fieldName, String fieldValue)
      Adds or replaces a MIME header field in one of the email's related items. If the header field does not exist, it is added. Otherwise it is replaced.

      Indexing: index is zero-based and must identify an existing related item. The change applies to the related item's MIME sub-header.

      Parameters:
      index - the index argument
      fieldName - the fieldName argument (not null)
      fieldValue - the fieldValue argument (not null)

    • addRelatedString

      public String addRelatedString​(String nameInHtml, String str, String charset)
      Adds a text-based related MIME resource, such as a style sheet, and returns the generated Content-ID.

      nameInHtml is the MIME filename or resource name, str contains the text content, and charset specifies the charset used to encode that content.

      The returned value is the bare Content-ID. It does not include angle brackets or the cid: prefix. This method does not modify the HTML body; the application must add or update the corresponding cid: reference itself.

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

    • addRelatedString2

      public void addRelatedString2​(String fileNameInHtml, String content, String charset)
      Adds a related item to the email from an in-memory string. Related items are things such as images and style sheets that are embedded within an HTML email. They are not considered attachments because their sole purpose is to participate in the display of the HTML.

      fileNameInHtml should be set to the filename used in an HTML img tag's src attribute, or to the URL referenced by an HTML link tag for a style sheet. content contains the Unicode text to add. charset specifies the charset to which content is converted before the MIME part is created, such as iso-8859-1, utf-8, or Shift_JIS.

      The resource is added as related content, not as a normal file attachment.

      Parameters:
      fileNameInHtml - the fileNameInHtml argument (not null)
      content - the content argument (not null)
      charset - the charset argument (not null)

    • addStringAttachment

      public void addStringAttachment​(String path, String content)
      Adds an attachment directly from a string in memory to the email.

      path supplies the filename placed in MIME, not a file to be read. content is the text content that becomes the attachment body.

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

    • addStringAttachment2

      public void addStringAttachment2​(String path, String content, String charset)
      Adds a text attachment using the in-memory string in content.

      path specifies the attachment filename; it is not a path to an existing local file. charset specifies the charset used to encode the string before it is added to the email.

      Note: charset may begin with bom- or no-bom- to require or suppress a byte-order mark for encodings such as UTF-8 or UTF-16. Examples include bom-utf-8 and no-bom-utf-8.

      This method is appropriate for text data already held in memory. For arbitrary binary bytes, use a BinData- or byte-based attachment method instead.

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

    • addTo

      public void addTo​(String friendlyName, String emailAddress)
      Adds a recipient to the to list. emailAddress is required, but friendlyName may be empty. Emails that have no To recipients will be sent to _LT_undisclosed-recipients_GT_.

      To add multiple recipients, call this method once per TO recipient.

      The recipient is added to the current in-memory message. Use getNumTo() and the To getter methods to inspect the resulting list.

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

    • addiCalendarAlternativeBody

      public void addiCalendarAlternativeBody​(String icalContent, String methodName)
      Adds or replaces an iCalendar body as a text/calendar alternative.

      If an iCalendar alternative already exists, it is replaced rather than duplicated. Repeated calls therefore leave at most one calendar alternative.

      icalContent contains the iCalendar data. methodName specifies the method parameter placed in the alternative body's Content-Type header, such as REQUEST or CANCEL. 

      BEGIN:VCALENDAR
 VERSION:2.0
 PRODID:-//hacksw/handcal//NONSGML v1.0//EN
 BEGIN:VEVENT
 UID:uid1@example.com
 DTSTAMP:19970714T170000Z
 ORGANIZER;CN=John Doe:MAILTO:john.doe@example.com
 DTSTART:19970714T170000Z
 DTEND:19970715T035959Z
 SUMMARY:Bastille Day Party
 END:VEVENT
 END:VCALENDAR

      For example, when methodName is REQUEST, the MIME headers for the alternative body include: 

      Content-Type: text/calendar; method=REQUEST
 Content-Transfer-Encoding: base64

      Calendar-aware mail clients may display this part as a meeting invitation, cancellation, or published event according to the iCalendar METHOD value and the contents of icalContent.

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

    • aesDecrypt

      public void aesDecrypt​(String password)
      Decrypts and restores an email message that was previously encrypted using aesEncrypt(String). password must be the same password that was passed as password to aesEncrypt(String).

      This is Chilkat's password-based email-object encryption counterpart to aesEncrypt(String); it is not S/MIME certificate-based decryption.

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

    • aesEncrypt

      public void aesEncrypt​(String password)
      Encrypts the email body, all alternative bodies, all message sub-parts, and attachments using 128-bit AES CBC encryption. To decrypt the email, call aesDecrypt(String) and pass the same value for password.

      The AesEncrypt/aesDecrypt(String) methods use symmetric password-based AES encryption and do not use certificates or private keys. The sending and receiving applications must both use Chilkat, and the value of password must be known by both applications.

      This is separate from S/MIME encryption controlled by getSendEncrypted().

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

    • appendToBody

      public void appendToBody​(String str)
      Appends a string to the plain-text body.

      If the message has only an HTML body, this method does not append HTML. Use setHtmlBody(String) or retrieve and reset the HTML body when HTML content must be extended.

      Parameters:
      str - the str argument (not null)

    • applyFixups

      public void applyFixups​(String fixups)
      Repairs selected MIME-formatting problems commonly found in email produced by other software.

      fixups is a comma-separated list of fixup keywords. The following keyword is currently defined:

      • FixRelated — Relocates HTML-related items, such as embedded images, into the appropriate MIME structure so they are not incorrectly presented as ordinary attachments.

      Fixups modify the current in-memory MIME structure. Apply them only when the input message exhibits the corresponding formatting problem.

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

    • aspUnpack

      public void aspUnpack​(String prefix, String saveDir, String urlPath, boolean cleanFiles)
      Unpacks an HTML email's body and its related items (images, style sheets, and the like) to the filesystem: each related part is written as a separate file, and the HTML is rewritten so those parts load as ordinary files instead of cid: references.

      Despite the "Asp" in the name (a historical artifact), this method is not limited to classic ASP. It is useful whenever an HTML email must be displayed or processed outside of a mail client, including:

      • Web display — rendering a message in webmail or any web application (PHP, ASP.NET, Node, Java, Python, and so on), where the browser loads the saved images and style sheets from a URL.
      • Archiving — saving an email as a self-contained, browsable HTML folder for long-term storage or compliance, viewable later without the original mail client.
      • Embedded viewers — loading the unpacked HTML into a desktop application's built-in browser or WebView control, which renders local files.
      • Format conversion — feeding the HTML to an HTML-to-PDF (or image) renderer that needs the related files present on disk.

      The arguments control the output: prefix is prepended to each saved filename, saveDir is the filesystem directory where files are written, urlPath is the URL base substituted into the rewritten HTML, and cleanFiles removes previously unpacked files first when set to true.

      For purely local viewing using relative paths rather than a web urlPath, see UnpackHtml. To instead produce a single self-contained MHT file that a WebBrowser control can display, see CreateTempMht.

      Parameters:
      prefix - the prefix argument (not null)
      saveDir - the saveDir argument (not null)
      urlPath - the urlPath argument (not null)
      cleanFiles - the cleanFiles argument
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • attachEmail

      public void attachEmail​(Email email)
      Attaches a copy of email to this email object. The attached email is encapsulated in a message/rfc822 subpart.

      A copy is attached, so later changes to email do not change the embedded message. The new part is counted by getNumAttachedMessages().

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

    • bEncodeString

      public String bEncodeString​(String str, String charset)
      Converts the Unicode string in str to the charset specified by charset, B-encodes the resulting multibyte data, and returns the encoded string.

      B-encoding is commonly used in RFC 2047 encoded words for non-ASCII MIME header text. charset controls the byte charset used before Base64 encoding.

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

    • clear

      public void clear()
      Removes the current message content, including recipients, headers, body representations, attachments, related items, and embedded messages. It does not delete or alter a message on a mail server.

      This method does not reset every configurable property. It resets message-oriented state such as getCharset(), getSendSigned(), getSendEncrypted(), getOverwriteExisting(), and getReturnReceipt() to their defaults.

      Other settings remain unchanged. In particular, replacement patterns and settings such as getSigningHashAlg(), getPkcs7KeyLength(), getOaepMgfHash(), getPrependHeaders(), and getUncommonOptions() are preserved.

      After clearing, the email has one default empty text body. When serialized, Chilkat can emit the standard headers for an empty email.

    • clearBcc

      public void clearBcc()
      Clears the list of blind carbon-copy recipients.

      This changes only the current email object and does not affect messages already sent.

    • clearCC

      public void clearCC()
      Clears the list of carbon-copy recipients.

      This changes only the current email object and does not affect messages already sent.

    • clearEncryptCerts

      public void clearEncryptCerts()
      Clears the internal list of explicitly specified certificates to be used for this encrypted email.

      This removes certificates added explicitly for future encryption operations. It does not remove certificates from the Windows certificate stores, the macOS Keychain, or any PFX source.

    • clearTo

      public void clearTo()
      Clears the list of to recipients.

      This changes only the current email object and does not affect messages already sent.

    • computeGlobalKey2

      public String computeGlobalKey2​(String encoding, boolean bFold)
      Computes a global unique key for the email. The key is created by a digest-MD5 hash of the concatenation of the following: 
      messageID + CRLF + subject + CRLF + from + CRLF + date + CRLF + recipientAddrs
 
 messageID contains the contents of the Message-ID header field.
 subject contains the contents of the Subject header field, trimmed of whitespace from both ends,
  where TAB characters are converted to SPACE characters, and internal whitespace is trimmed so that
  no more than one SPACE char in a row exists.
 from contains the lowercase From header email address.
 date contains the contents of the Date header field.
 toAddrs contains lowercase To and Cc recipient email addresses, comma-separated, with duplicates removed, and sorted
  in ascending order. The BCC addresses are NOT included.
 
 (After calling this method, the LastErrorText property can be examined to see the string that was hashed.)

      The 16-byte MD5 hash is returned as an encoded string. encoding determines the encoding: base64, hex, url, etc. If bFold is true, then the 16-byte MD5 hash is folded to 8 bytes with an XOR to produce a shorter key.

      The result is intended as a deterministic message key for indexing or duplicate detection. It is separate from the MIME Message-ID and does not modify the email.

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

    • convertInlineImages

      public void convertInlineImages()
      Converts images embedded inline within HTML to multipart/related MIME parts referenced from the HTML by CID.

      This is useful for producing conventional HTML email where image data is stored in MIME parts rather than directly in the HTML. Review the resulting HTML and related-item collection after conversion.

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

    • createTempMht

      public String createTempMht​(String inFilename)
      Prepares the email for display in a web browser and saves it as a temporary MHT (MIME HTML) file, returning the path to the file. If inFilename is empty, a temporary filename is generated automatically.

      To make the message viewable as a standalone web page, this method transforms the email as follows:

      • All attachments are dropped.
      • If the email has both HTML and plain-text alternatives, the plain-text alternative is dropped.
      • If the email has only a plain-text body, that body is converted to HTML.

      The resulting MHT file can be loaded by a WebBrowser control (or any viewer that understands MHT) to render the message, inline images and all. To instead unpack the HTML and its related files to loose files served by a web application, see AspUnpack.

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

    • dropAttachments

      public void dropAttachments()
      Removes all attachments from the email.

      This removes ordinary file attachments from the in-memory message. Related items and attached message/rfc822 emails are separate and are not described by this method.

    • dropRelatedItem

      public void dropRelatedItem​(int index)
      A related item is typically an embedded image referenced from the HTML in the email via a CID hyperlink. This method removes the Nth embedded image from the email. Note: If the HTML tries to reference the removed image, it will be displayed as a broken image link.

      This changes only the current in-memory Email object and does not delete or alter a message on a mail server.

      Parameters:
      index - the index argument

    • dropRelatedItems

      public void dropRelatedItems()
      A related item is typically an embedded image referenced from the HTML in the email via a CID hyperlink. This method removes all the embedded images from the email.

      This removes related MIME resources from the in-memory message. It does not remove ordinary attachments.

    • dropSingleAttachment

      public void dropSingleAttachment​(int index)
      Removes the attachment at the zero-based index specified by index.

      index is zero-based; valid values are from 0 through getNumAttachments() - 1.

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

    • generateFilename

      public String generateFilename()
      Generates a unique filename for this email. The filename will be different each time the method is called.

      This method returns a filename only; it does not create a file. It is useful when saving many messages and a collision-resistant local name is needed.

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

    • getAltHeaderField

      public String getAltHeaderField​(int index, String fieldName)
      Returns the value of a header field within the Nth alternative body's MIME sub-part.

      index is zero-based and refers to an alternative counted by getNumAlternatives(). fieldName names the MIME header field within that alternative part.

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

    • getAlternativeBody

      public String getAlternativeBody​(int index)
      Returns the Nth alternative body. The getNumAlternatives() property tells the number of alternative bodies present. Use the getHtmlBody() and getPlainTextBody() methods to easily get the HTML or plain text alternative bodies.

      index is zero-based; valid values are from 0 through getNumAlternatives() - 1.

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

    • getAlternativeBodyBd

      public void getAlternativeBodyBd​(int index, BinData binData)
      Returns the contents of the Nth alternative body to binData. The first alternative body is at index 0. This method should only be called when the getNumAlternatives() property has a value greater than 0.

      index is zero-based; valid values are from 0 through getNumAlternatives() - 1. binData receives the body bytes.

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

    • getAlternativeBodyByContentType

      public String getAlternativeBodyByContentType​(String contentType)
      Returns the alternative body by Content-Type, such as text/plain, text/html, text/xml, etc.

      The lookup is useful when the alternative order is not known. Typical values for contentType are text/plain and text/html.

      Parameters:
      contentType - the contentType argument (not null)
      Returns:
      the result, or null if not found (no exception is thrown in that case)

    • getAlternativeContentType

      public String getAlternativeContentType​(int index)
      Returns the content type of the Nth alternative body. The getNumAlternatives() property tells the number of alternative bodies present.

      index is zero-based; valid values are from 0 through getNumAlternatives() - 1.

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

    • getAttachedEmail

      public void getAttachedEmail​(int index, Email email)
      Copies the Nth embedded message/rfc822 MIME part into email.

      index is zero-based; valid values are from 0 through getNumAttachedMessages() - 1. email is replaced with an independent copy of the embedded message. Modifying email does not change the embedded message stored in the caller.

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

    • getAttachedMessageAttr

      public String getAttachedMessageAttr​(int index, String fieldName, String attrName)
      Returns a header field attribute value for the Nth attached (embedded) email. For example, to get the value of the name attribute in the Content-Type header for the first attached message: 
      Content-Type: message/rfc822; name="md75000024149.eml"

      then the method arguments should contain the values 0, Content-Type, name.

      index is a zero-based attached-message index. fieldName names a MIME header field and attrName names one of that field's parameters.

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

    • getAttachedMessageFilename

      public String getAttachedMessageFilename​(int index)
      Returns the filename of the Nth attached (embedded) email. The filename is the filename attribute of the Content-Disposition header field found within the Nth message/rfc822 sub-part of the calling email object.

      Important: The attached message filename is only present if the Content-Disposition header exists AND contains a filename attribute. If questions arise, one could open the email in a text editor to examine the MIME sub-header for the attached message (where the Content-Type = message/rfc822). For example, here is a sub-header that has a filename: 

      Content-Type: message/rfc822; name="GetAttachedMessageAttr.eml"
 Content-Transfer-Encoding: 7bit
 Content-Disposition: attachment; filename="GetAttachedMessageAttr.eml"

      Here is an attached message sub-header that does NOT have a filename: 

      Content-Type: message/rfc822
 Content-Transfer-Encoding: 7bit
 Content-Disposition: attachment

      index is zero-based. The returned value comes from MIME metadata and should be sanitized before it is used as a local filesystem name.

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

    • getAttachmentAttr

      public String getAttachmentAttr​(int index, String fieldName, String attrName)
      Returns a header field attribute value from the header field of the Nth attachment.

      index is a zero-based attachment index. fieldName names a header field such as Content-Type, and attrName names one of that field's parameters, such as charset or name.

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

    • getAttachmentBd

      public void getAttachmentBd​(int index, BinData binData)
      Copies an attachment's binary data into binData. The first attachment is at index 0.

      index is zero-based. binData receives the attachment bytes.

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

    • getAttachmentContentID

      public String getAttachmentContentID​(int index)
      Returns the ContentID header field for the Nth attachment. The first attachment is at index 0.

      index is zero-based. The returned value is the identifier used by cid: references when the attachment is referenced inline.

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

    • getAttachmentContentType

      public String getAttachmentContentType​(int index)
      Returns the Content-Type header field for the Nth attachment. Indexing of attachments begins at 0.

      index is zero-based. The result is the MIME media type without implying that the filename extension is trustworthy.

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

    • getAttachmentFilename

      public String getAttachmentFilename​(int index)
      Retrieves an attachment's filename.

      index is zero-based. The returned value is the filename stored in MIME. It may contain path information or characters that are not valid in a local filesystem filename. When saveAllAttachments(String) or saveAttachedFile(int, String) saves the attachment, Chilkat ignores MIME path components and sanitizes the final filename as described by those methods.

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

    • getAttachmentHeader

      public String getAttachmentHeader​(int attachIndex, String fieldName)
      Returns the value of a header field (by name) of an attachment.

      attachIndex is a zero-based attachment index and fieldName is the MIME header-field name. Header-field names are case-insensitive.

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

    • getAttachmentSize

      public int getAttachmentSize​(int index)
      Returns the size, in bytes, of the attachment at the zero-based index specified by index. Returns -1 if index does not identify an existing attachment.

      The returned value is the decoded attachment content size, not the number of Base64 characters in the MIME representation.

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

    • getAttachmentString

      public String getAttachmentString​(int index, String charset)
      Returns the attachment at the zero-based index specified by index as text.

      charset specifies the charset used to interpret the attachment bytes, such as utf-8. CRLF sequences in the attachment are normalized to single newline characters in the returned string.

      index is zero-based. charset controls conversion of the attachment bytes to Unicode; use a binary attachment getter when the content is not text.

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

    • getAttachmentStringCrLf

      public String getAttachmentStringCrLf​(int index, String charset)
      Retrieves an attachment's data as a String. All end-of-lines will be translated to CRLF sequences.

      index is a zero-based attachment index. charset specifies the charset used to decode the attachment bytes to Unicode text.

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

    • getBcc

      public String getBcc​(int index)
      Returns a blind carbon-copy recipient's full email address.

      index is zero-based; valid values are from 0 through getNumBcc() - 1. The result may include both display name and address.

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

    • getBccAddr

      public String getBccAddr​(int index)
      Returns the Nth BCC address (only the address part, not the friendly-name part).

      index is zero-based; valid values are from 0 through getNumBcc() - 1.

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

    • getBccName

      public String getBccName​(int index)
      Returns the Nth BCC name (only the friendly-name part, not the address part).

      index is zero-based; valid values are from 0 through getNumBcc() - 1.

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

    • getCC

      public String getCC​(int index)
      Returns a carbon-copy recipient's full email address.

      index is zero-based; valid values are from 0 through getNumCC() - 1. The result may include both display name and address.

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

    • getCcAddr

      public String getCcAddr​(int index)
      Returns the Nth CC address (only the address part, not the friendly-name part).

      index is zero-based; valid values are from 0 through getNumCC() - 1.

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

    • getCcName

      public String getCcName​(int index)
      Returns the Nth CC name (only the friendly-name part, not the address part).

      index is zero-based; valid values are from 0 through getNumCC() - 1.

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

    • getDeliveryStatusInfo

      public String getDeliveryStatusInfo​(String fieldName)
      Returns a field from the message/delivery-status part of a delivery-status notification.

      Call this method only for an email identified as a multipart/report delivery-status notification. fieldName specifies the field name, such as Final-Recipient, Status, Action, or Reporting-MTA. 

      Reporting-MTA: dns; XYZ.abc.nl
 
 Final-Recipient: RFC822; someEmailAddr@doesnotexist123.nl
 Action: failed
 Status: 5.4.4

      fieldName names a field in the delivery-status section. This method reads the report already present in the email object and performs no server query.

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

    • getDigestEmail

      public void getDigestEmail​(int index, Email email)
      Returns in email the Nth digest email contained within a multipart/digest. The first digest is at index 0. Use the getNumDigests() property to get the number of digests available.

      index is zero-based; valid values are from 0 through getNumDigests() - 1. email receives a copy of the digest message.

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

    • getDsnInfo

      public void getDsnInfo​(JsonObject json)
      If the isMultipartReport() method indicates that the email is multipart/report, use this method to obtain the delivery-status information, including the final recipients, as JSON that is easy to parse.

      The JSON is derived from report data already contained in the email; the method does not contact an SMTP server for updated status.

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

    • getHeaderField

      public String getHeaderField​(String fieldName)
      Returns the value of a header field.

      Header-field names are case-insensitive. If a field occurs more than once, use indexed header enumeration when each occurrence must be inspected separately.

      Parameters:
      fieldName - the fieldName argument (not null)
      Returns:
      the result, or null if not found (no exception is thrown in that case)

    • getHeaderFieldName

      public String getHeaderFieldName​(int index)
      Returns the name of the Nth header field. The getNumHeaderFields() property gives the number of header fields. Use getHeaderField(String) to retrieve a header field value by name.

      The first header field is at index 0. (All Chilkat indexing is 0-based.)

      index is zero-based; valid values are from 0 through getNumHeaderFields() - 1. Repeated fields appear as separate entries.

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

    • getHeaderFieldValue

      public String getHeaderFieldValue​(int index)
      Returns the value of the Nth header field. (Indexing begins at 0) The number of header fields can be obtained from the getNumHeaderFields() property.

      The first header field is at index 0, the last header field is at index getNumHeaderFields()-1. (All Chilkat indexing is 0-based.)

      index is zero-based; valid values are from 0 through getNumHeaderFields() - 1. Use the same index with getHeaderFieldName(int) to identify the field.

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

    • getHtmlBody

      public String getHtmlBody()
      Returns the body having the text/html content type.

      This reads the HTML representation already present in the email object. It does not automatically inline related images; use getHtmlBodySb(boolean, StringBuilder) for that option.

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

    • getHtmlBodySb

      public void getHtmlBodySb​(boolean inlineImageData, StringBuilder sb)
      Returns the body having the text/html content type. If inlineImageData is true, the related images found in the MIME are inlined as base64 directly within the returned HTML. The HTML is returned in sb.

      Inlining related images can substantially increase the size of the returned HTML because the image bytes are embedded as data URLs.

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

    • getImapUid

      public long getImapUid()
      When email headers are downloaded from an IMAP server (using Chilkat IMAP), a ckx-imap-uid header field is added. The content of this header is the UID or sequence number of the email on the IMAP server. In addition, a ckx-imap-isUid header field is added, and this will have the value YES or NO. If the value is YES, then ckx-imap-uid contains a UID, if the value is NO, then ckx-imap-uid contains the sequence number. This method returns the UID if ckx-imap-uid exists and contains a UID, otherwise it returns 0xFFFFFFFF.

      An application that wishes to download the full email would use this UID and then call the Chilkat IMAP object's FetchSingle or FetchSingleAsMime methods.

      Note: If an email was downloaded from the IMAP server in a way such that the UID is not received, then there will be no ckx-imap-uid header field and this method would return 0xFFFFFFFF. For example, if emails are downloaded by sequence numbers via the Imap.FetchSequence method, then UIDs are not used and therefore the email object will not contain this information.

      This reads Chilkat metadata stored in the email object; it does not contact the IMAP server. The accompanying Boolean output distinguishes a stable UID from a mailbox sequence number.

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

    • getMime

      public String getMime()
      Returns the email as RFC822/MIME text containing the headers, body representations, related items, and attachments.

      The result is suitable for saving as an .eml file or passing to an API that accepts MIME text.

      Serialization may normalize header whitespace, Content-Type parameters, transfer encodings, and other MIME formatting. Therefore, MIME that is loaded and then reserialized is not guaranteed to be byte-for-byte identical to the original input. Repeated calls without modifying the email return the same current serialized form.

      Headers that were explicitly removed, such as Date, Message-ID, or MIME-Version, are not necessarily regenerated by this method.

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

    • getMimeBd

      public void getMimeBd​(BinData bindat)
      Serializes the complete RFC822/MIME message and appends the bytes to bindat.

      The output includes headers, body representations, related items, and attachments. Clear bindat first when replacement rather than append behavior is desired.

      Serialization may normalize header whitespace, Content-Type parameters, transfer encodings, and other MIME formatting. Loading MIME and then calling this method is therefore not guaranteed to reproduce the original input byte-for-byte.

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

    • getMimeSb

      public void getMimeSb​(StringBuilder sb)
      Returns the email as MIME text containing the email header, body (or bodies), related items (if any), and all attachments. The MIME is appended to the existing contents (if any) of sb.

      Clear sb first when replacement rather than append behavior is desired.

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

    • getNthBinaryPartOfTypeBd

      public void getNthBinaryPartOfTypeBd​(int index, String contentType, boolean inlineOnly, boolean excludeAttachments, BinData bd)
      Loads bd with the binary bytes of the Nth MIME sub-part matching contentType, which can be an exact Content-Type such as application/pdf, or a wildcarded Content-Type such as application/*, or */*. Indexing begins at 0. Call getNumPartsOfType(String, boolean, boolean) to find out how many MIME sub-parts exist for any given content type. If inlineOnly is true, then only MIME sub-parts having a Content-Disposition of inline are included. If excludeAttachments is true, then MIME sub-parts having a Content-Disposition of attachment are excluded.

      Note: If the email was downloaded as header-only, it will not contain all the parts of the full email. Also, if downloaded from IMAP excluding attachments, those parts that are the attachments will (of course) be missing.

      Note: Beginning in v9.5.0.95, contentType can be wildcarded. For example, it is possible to specify text/*, or simply * to match any Content-Type.

      Note: Only non-multipart MIME parts are matched.

      Use getNumPartsOfType(String, boolean, boolean) with the same filters to determine the valid zero-based index range before loading bd.

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

    • getNthContentType

      public String getNthContentType​(int index, String contentType, boolean inlineOnly, boolean excludeAttachments)
      Returns the Content-Type of the Nth non-multipart MIME part matching the pattern in contentType. index is a zero-based index among the matching parts.

      contentType may be an exact Content-Type, such as text/plain, or a wildcard pattern, such as text/* or *. When inlineOnly is true, only parts having an inline Content-Disposition are considered. When excludeAttachments is true, parts having an attachment Content-Disposition are excluded.

      Use getNumPartsOfType(String, boolean, boolean) with the same filters to determine the valid zero-based index range.

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

    • getNthTextPartOfType

      public String getNthTextPartOfType​(int index, String contentType, boolean inlineOnly, boolean excludeAttachments)
      Returns the text content of the Nth non-multipart MIME part matching the Content-Type pattern in contentType. index is a zero-based index among the matching parts.

      contentType may be an exact Content-Type, such as text/plain, or a wildcard pattern, such as text/* or *. Use getNumPartsOfType(String, boolean, boolean) to determine the number of matching parts.

      When inlineOnly is true, only parts having an inline Content-Disposition are considered. When excludeAttachments is true, parts having an attachment Content-Disposition are excluded.

      Note: A header-only email, or an email downloaded from IMAP without attachments, does not contain every MIME part from the complete message.

      Use getNumPartsOfType(String, boolean, boolean) with the same filters to determine the valid zero-based index range before retrieving a part.

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

    • getNumPartsOfType

      public int getNumPartsOfType​(String contentType, boolean inlineOnly, boolean excludeAttachments)
      Returns the number of non-multipart MIME parts matching the Content-Type pattern in contentType.

      contentType may be an exact Content-Type, such as text/plain, or a wildcard pattern, such as text/* or *. When inlineOnly is true, only parts having an inline Content-Disposition are counted. When excludeAttachments is true, parts having an attachment Content-Disposition are excluded.

      Note: A header-only email, or an email downloaded from IMAP without attachments, does not contain every MIME part from the complete message.

      The count is based on the MIME parts currently loaded in the email object. No attachment or body data is fetched from a server by this method.

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

    • getPlainTextBody

      public String getPlainTextBody()
      Returns the email body having the text/plain content type.

      This reads the plain-text representation already present in the email object. It does not convert the HTML body to plain text.

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

    • getRelatedAttr

      public String getRelatedAttr​(int index, String fieldName, String attrName)
      Returns a header field attribute value from the header field of the Nth related item.

      index is a zero-based related-item index. fieldName names a MIME header field and attrName names one of that field's parameters.

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

    • getRelatedContentID

      public String getRelatedContentID​(int index)
      Returns the content ID of a related item contained with the email. Related items are typically images and style-sheets embedded within HTML emails.

      index is zero-based; valid values are from 0 through getNumRelatedItems() - 1. The value is normally referenced from HTML as a cid: URL.

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

    • getRelatedContentLocation

      public String getRelatedContentLocation​(int index)
      Returns the Content-Location of a related item contained with the email. Related items are typically images and style-sheets embedded within HTML emails.

      index is zero-based. Content-Location is an alternative to Content-ID for identifying a resource referenced by the HTML body.

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

    • getRelatedContentType

      public String getRelatedContentType​(int index)
      Returns the Content-Type of the Nth related content item in an email message.

      index is zero-based; valid values are from 0 through getNumRelatedItems() - 1.

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

    • getRelatedFilename

      public String getRelatedFilename​(int index)
      Returns the filename of a related item contained with the email. Related items are typically images and style-sheets embedded within HTML emails.

      index is zero-based. The returned MIME filename should be sanitized before it is used as a local filesystem path.

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

    • getRelatedHeader

      public String getRelatedHeader​(int index, String fieldName)
      Returns the value of a header field (by name) of a related item.

      index is a zero-based related-item index. MIME header-field names are case-insensitive.

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

    • getRelatedString

      public String getRelatedString​(int index, String charset)
      Returns the text with CR line-endings of a related item contained with the email. Related items are typically images and style-sheets embedded within HTML emails.

      index is zero-based and charset specifies the charset used to decode the related-item bytes to Unicode text.

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

    • getRelatedStringCrLf

      public String getRelatedStringCrLf​(int index, String charset)
      Returns the text with CRLF line-endings of a related item contained with the email. Related items are typically images and style-sheets embedded within HTML emails.

      index is zero-based and charset specifies the charset used to decode the related-item bytes to Unicode text.

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

    • getReplacePattern

      public String getReplacePattern​(int index)
      Returns a replacement pattern previously defined for mail-merge operations.

      index is zero-based; valid values are from 0 through getNumReplacePatterns() - 1.

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

    • getReplaceString

      public String getReplaceString​(int index)
      Returns a replacement string for a previously defined pattern/replacement string pair. (This is a mail-merge feature.)

      Note: This method was found to not be working correctly and is fixed in Chilkat v9.5.0.91.

      index is a zero-based pattern index. Use getNumReplacePatterns() to determine the valid range.

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

    • getReplaceString2

      public String getReplaceString2​(String pattern)
      Returns a replacement string for a previously defined pattern/replacement string pair. (This is a mail-merge feature.)

      pattern is the previously registered pattern text, not a numeric index.

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

    • getReport

      public String getReport​(int index)
      (See the getNumReports() property.) Returns the body content of the Nth report within a multipart/report email.

      Multipart/report is a message type that contains data formatted for a mail server to read. It is split between a text/plain (or some other content/type easily readable) and a message/delivery-status, which contains the data formatted for the mail server to read.

      It is defined in RFC 3462

      index is zero-based; valid values are from 0 through getNumReports() - 1.

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

    • getTo

      public String getTo​(int index)
      Returns a to recipient's full email address.

      index is zero-based; valid values are from 0 through getNumTo() - 1. The result may include both display name and address.

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

    • getToAddr

      public String getToAddr​(int index)
      Returns the Nth To address (only the address part, not the friendly-name part).

      index is zero-based; valid values are from 0 through getNumTo() - 1.

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

    • getToName

      public String getToName​(int index)
      Returns the Nth To name (only the friendly-name part, not the address part).

      index is zero-based; valid values are from 0 through getNumTo() - 1.

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

    • getXml

      public String getXml()
      Convert the email object to an XML document in memory

      The XML is Chilkat's email-object representation, not MIME and not a standardized interchange format. Use getMime() when an RFC822/MIME message is required.

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

    • hasHeaderMatching

      public boolean hasHeaderMatching​(String fieldName, String valuePattern, boolean caseSensitive)
      Returns true when the email contains a header field named fieldName whose value matches the wildcard pattern in valuePattern.

      valuePattern may contain any number of * characters, where each asterisk matches zero or more characters. caseSensitive controls whether matching is case-sensitive.

      The pattern syntax is a simple wildcard match, not a regular expression. Header-field names are compared without regard to case.

      Parameters:
      fieldName - the fieldName argument (not null)
      valuePattern - the valuePattern argument (not null)
      caseSensitive - the caseSensitive argument
      Returns:
      the result; this method never throws ChilkatException

    • hasHtmlBody

      public boolean hasHtmlBody()
      Returns true if the email has an HTML body.

      Returns true only when a text/html body is present in the current email object.

      Returns:
      the result; this method never throws ChilkatException

    • hasPlainTextBody

      public boolean hasPlainTextBody()
      Returns true if the email has a plain-text body.

      Returns true only when a text/plain body is present in the current email object.

      Returns:
      the result; this method never throws ChilkatException

    • isMultipartReport

      public boolean isMultipartReport()
      Returns true if the email is a multipart/report email.

      Returns true when the top-level message structure is a multipart/report. Use getDsnInfo(JsonObject) or getReport(int) to examine report content.

      Returns:
      the result; this method never throws ChilkatException

    • lastDecryptCert

      public void lastDecryptCert​(Cert cert)
      Returns in cert the certificate used to decrypt this email.

      Call this after a successful decryption to inspect the certificate associated with the private key that decrypted the message.

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

    • lastSignerCert

      public void lastSignerCert​(int index, Cert cert)
      Copies the certificate for the signer at the zero-based index specified by index into cert.

      Most signed emails have one signer, but an email may contain multiple signatures.

      Call this after parsing or verifying a signed message. cert receives a copy of the signer certificate and can be examined independently.

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

    • linkedDomains

      public void linkedDomains​(StringTable domains)
      Extracts domain names from hyperlinks in an HTML email. Lowercase domains are appended to domains without creating duplicates.

      This method parses links only; it does not perform DNS lookups or make network requests to the extracted domains.

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

    • loadEml

      public void loadEml​(String mimePath)
      Loads a complete email from an .eml file. An EML file contains RFC822/MIME message text.

      On success, the loaded message replaces the entire current email, including recipients, headers, bodies, related items, and attachments. If the file cannot be opened or parsed and the method fails, the email content that existed before the call is preserved.

      The file is parsed locally; this method does not connect to an SMTP, POP3, or IMAP server.

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

    • loadXml

      public void loadXml​(String xmlPath)
      Loads an email from a Chilkat XML email file.

      On success, the loaded message replaces the entire current email, including recipients, headers, bodies, related items, and attachments. If the file cannot be opened or parsed and the method fails, the email content that existed before the call is preserved.

      The file must contain XML previously produced by Chilkat email serialization. It is not an arbitrary XML-to-email conversion method.

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

    • loadXmlString

      public void loadXmlString​(String xmlStr)
      Loads an email from the Chilkat XML representation in xmlStr, typically obtained from getXml().

      On success, the loaded message replaces the entire current email, including recipients, headers, bodies, related items, and attachments. If xmlStr cannot be parsed and the method fails, the email content that existed before the call is preserved.

      This is a local parsing operation and does not connect to a mail server.

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

    • makeCopy

      public void makeCopy​(Email destEmail)
      Copies the entire state of this email into destEmail, including all message content, recipients, headers, body representations, attachments, related items, embedded messages, replacement patterns, certificates, certificate sources, and configuration properties.

      destEmail becomes an independent copy. Subsequent changes to either email object do not affect the other.

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

    • qEncodeString

      public String qEncodeString​(String str, String charset)
      Converts the Unicode string in str to the charset specified by charset, Q-encodes the resulting multibyte data, and returns the encoded string.

      Q-encoding is commonly used in RFC 2047 encoded words for non-ASCII MIME header text. charset controls the byte charset used before Q-encoding.

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

    • removeAttachedMessage

      public void removeAttachedMessage​(int idx)
      Removes the Nth message/rfc822 sub-part of the email. Indexing begins at 0.

      idx is zero-based; valid values are from 0 through getNumAttachedMessages() - 1. This changes only the in-memory email.

      Parameters:
      idx - the idx argument

    • removeAttachedMessages

      public void removeAttachedMessages()
      Removes all message/rfc822 sub-parts of the email object.

      This does not remove ordinary file attachments or related HTML resources.

    • removeAttachmentPaths

      public void removeAttachmentPaths()
      Removes relative or absolute path information from attachment filenames stored in the MIME, leaving only each final filename component.

      This changes the MIME filename metadata only. It does not affect the behavior of saveAllAttachments(String) or saveAttachedFile(int, String), because those methods already ignore path information in MIME attachment filenames and save beneath the directory specified by the application.

    • removeHeaderField

      public void removeHeaderField​(String fieldName)
      Removes by name all occurrences of a header field.

      Header-field names are case-insensitive. All repeated occurrences having the specified name are removed from the current email object.

      Parameters:
      fieldName - the fieldName argument (not null)

    • removeHtmlAlternative

      public void removeHtmlAlternative()
      Removes the HTML body from the email (if an HTML body exists).

      Other body representations, attachments, and related items remain unchanged.

    • removePlainTextAlternative

      public void removePlainTextAlternative()
      Removes the plain-text body from the email (if a plain-text body exists).

      Other body representations, attachments, and related items remain unchanged.

    • saveAllAttachments

      public void saveAllAttachments​(String dirPath)
      Saves all attachments to the directory specified by dirPath. If dirPath or any of its directory components do not exist, Chilkat creates them automatically. The getOverwriteExisting() property controls whether existing files may be overwritten.

      Chilkat first uses the filename from the MIME Content-Disposition header. If no filename is present there, it uses the name parameter from the Content-Type header. If neither is present, the attachment is saved as attachedFile.txt.

      If the selected MIME filename contains relative or absolute path information, Chilkat ignores the path and uses only the final filename component. The file is always written beneath the application-specified directory in dirPath.

      On Windows, Chilkat converts the final MIME filename component to a valid Windows filename. It replaces | and a : that is not part of a drive specification with _; removes <, >, *, ?, and "; and interprets / and \ as path separators, so the path is omitted. If the colon belongs to a drive specification such as C:\, it is discarded with the path. For example, a<b>c:d|e?f*g.txt is saved as abc_d_efg.txt.

      Attachment filenames can be changed before saving. The number of attachments is available in the getNumAttachments() property. An application can call getAttachmentFilename(int) for each zero-based index and change a filename by calling setAttachmentFilename(int, String).

      Only attachments already present in the email object are saved. A message downloaded without attachment bodies must first have those bodies fetched by the mail protocol component.

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

    • saveAttachedFile

      public void saveAttachedFile​(int index, String dirPath)
      Saves the attachment at the zero-based index specified by index to the directory specified by dirPath. If dirPath or any of its directory components do not exist, Chilkat creates them automatically. The getOverwriteExisting() property controls whether an existing file may be overwritten.

      Chilkat first uses the filename from the MIME Content-Disposition header. If no filename is present there, it uses the name parameter from the Content-Type header. If neither is present, the attachment is saved as attachedFile.txt.

      If the selected MIME filename contains relative or absolute path information, Chilkat ignores the path and uses only the final filename component. The file is always written beneath the application-specified directory in dirPath.

      On Windows, Chilkat converts the final MIME filename component to a valid Windows filename. It replaces | and a : that is not part of a drive specification with _; removes <, >, *, ?, and "; and interprets / and \ as path separators, so the path is omitted. If the colon belongs to a drive specification such as C:\, it is discarded with the path. For example, a<b>c:d|e?f*g.txt is saved as abc_d_efg.txt.

      The attachment data must already be present in the current Email object. This method does not retrieve missing attachment data from a mail server.

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

    • saveEml

      public void saveEml​(String emlFilePath)
      Convert this email object to EML and save it to a file.

      An EML file contains the complete RFC822/MIME message, including headers, bodies, related items, and attachments.

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

    • saveRelatedItem

      public void saveRelatedItem​(int index, String dirPath)
      Saves the related item at the zero-based index specified by index to the directory specified by dirPath. If dirPath or any of its directory components do not exist, Chilkat creates them automatically. Valid indexes are from 0 through getNumRelatedItems() - 1. The getOverwriteExisting() property controls whether an existing file may be overwritten.

      If the related item's MIME filename contains relative or absolute path information, Chilkat ignores the path and uses only the final filename component. The file is always written beneath the application-specified directory in dirPath.

      Related items are typically images, style sheets, or other resources used by an HTML body. The related-item data must already be present in the email object.

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

    • saveXml

      public void saveXml​(String path)
      Convert this email object to XML and save it to a file.

      The generated XML is Chilkat's email-object serialization and can later be loaded with loadXml(String). Use saveEml(String) for a standard MIME message file.

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

    • setAttachmentCharset

      public void setAttachmentCharset​(int index, String charset)
      Sets the charset parameter of the Content-Type header field for the attachment at the zero-based index specified by index. charset specifies the charset, such as Shift_JIS, iso-8859-2, big5, or iso-8859-5.

      This updates MIME metadata and does not transcode the attachment bytes. Use it only when the bytes are already encoded in the charset specified by charset.

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

    • setAttachmentDisposition

      public void setAttachmentDisposition​(int index, String disposition)
      Sets the Content-Disposition value for the attachment at the zero-based index specified by index.

      The default disposition is attachment. Set disposition to inline when the attachment should be presented as inline content.

      index is zero-based. inline suggests that a mail client may display the part in the message, while attachment suggests a separate downloadable file.

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

    • setAttachmentFilename

      public void setAttachmentFilename​(int index, String filename)
      Changes the filename of the attachment at the zero-based index specified by index. filename contains the new filename.

      index is zero-based. This changes the filename stored in MIME and does not rename any original local file.

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

    • setBodyBd

      public void setBodyBd​(BinData bd, String contentType, String disposition, String filename)
      Sets the main email body from the binary data in bd.

      contentType specifies the MIME Content-Type. disposition specifies the disposition and may be empty, inline, or attachment. filename optionally specifies a filename. When filename is provided, disposition must also be specified because the filename is an attribute of the Content-Disposition header.

      This replaces the main body using bytes already stored in bd. It does not add a separate attachment unless disposition and filename intentionally describe the body as one.

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

    • setDecryptCert

      public void setDecryptCert​(Cert cert)
      Allows for a certificate to be explicitly provided for decryption. When an email object is loaded via any method, such as loadEml(String), setFromMimeText(String), SetFromMimeBytes, etc., security layers (signatures and encryption) are automatically unwrapped. This method could be called prior to calling a method that loads the email.

      Configure the certificate before loading or unwrapping the encrypted MIME so the private key is available at decryption time.

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

    • setDecryptCert2

      public void setDecryptCert2​(Cert cert, PrivateKey key)
      Explicitly provides the certificate in cert and the corresponding private key in key for decryption. When an email object is loaded by a method such as loadEml(String), setFromMimeText(String), or SetFromMimeBytes, security layers such as signatures and encryption are automatically unwrapped. Decryption requires the private key in key.

      On Windows, Chilkat automatically searches the system certificate stores for the required certificate and private key. On macOS, Chilkat automatically searches the Keychain. When the required certificate and private key are not installed in one of these locations, provide them in cert and key, or call addPfxSourceFile(String, String) or AddPfxSourceData.

      Call this method before loading or unwrapping the encrypted MIME. cert and key must correspond to one another.

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

    • setDt

      public void setDt​(DateTime dt)
      Sets the Date header field of the email to have the value of the date/time object provided.

      The date/time is formatted as an RFC822 Date header when the message is serialized.

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

    • setEdifactBody

      public void setEdifactBody​(String message, String name, String filename, String charset)
      Creates a typical email used to send EDIFACT messages. Does the following:
      1. Sets the email body to the EDIFACT message passed in message.
      2. Sets the Content-Transfer-Encoding to Base64.
      3. Set the Content-Type equal to application/EDIFACT.
      4. Sets the Content-Type header's name attribute to name.
      5. Sets the Content-Disposition equal to attachment.
      6. Sets the Content-Disposition's filename attribute equal to filename.
      7. The EDIFACT message is converted to the charset indicated by charset, and encoded using Base64 in the email body.

      The email's subject, recipients, FROM address, and other headers are left unmodified.

      This is a convenience method that constructs the customary MIME headers and body for EDIFACT transport. It replaces the existing main body configuration.

      Parameters:
      message - the message argument (not null)
      name - the name argument (not null)
      filename - the filename argument (not null)
      charset - the charset argument (not null)

    • setEncryptCert

      public void setEncryptCert​(Cert cert)
      Sets the certificate in cert as the explicit recipient encryption certificate. Use the CreateCS, CertStore, and Cert classes to obtain a Cert object by locating a certificate in a certificate store or loading one from a file.

      Use addEncryptCert(Cert) instead when the message must be decryptable by multiple recipients.

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

    • setFromMimeBd

      public void setFromMimeBd​(BinData bindat)
      Loads an email with the MIME stored in a BinData object.

      Note: This replaces the entire contents of the email object, including the To/CC recipients.

      The MIME is parsed locally and the BinData itself is not modified.

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

    • setFromMimeSb

      public void setFromMimeSb​(StringBuilder sb)
      Loads an email with the MIME stored in a StringBuilder object.

      Note: This replaces the entire contents of the email object, including the To/CC recipients.

      The MIME is parsed locally and the StringBuilder itself is not modified.

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

    • setFromMimeText

      public void setFromMimeText​(String mimeText)
      Loads the email from MIME text contained in mimeText, such as the contents of an .eml file.

      On success, this replaces the entire current email, including recipients, headers, bodies, related items, and attachments. An empty string is accepted and clears the current message content.

      mimeText must be interpreted as MIME, not as body text. To set a plain-text body directly, use the getBody() property or setTextBody(String, String).

      This parses MIME already present in memory and does not contact a mail server.

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

    • setFromXmlText

      public void setFromXmlText​(String xmlStr)
      Loads an email from an XML string.

      Note: This replaces the entire contents of the email object, including the To/CC recipients.

      The XML must be in Chilkat's email serialization format, typically obtained from getXml().

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

    • setHtmlBody

      public void setHtmlBody​(String html)
      Sets the HTML body of an email.

      This creates or replaces the text/html body. It does not automatically create a plain-text alternative.

      Parameters:
      html - the html argument (not null)

    • setRelatedFilename

      public void setRelatedFilename​(int index, String path)
      Sets the filename for a related item within the email.

      index is zero-based. This changes the filename stored in the related MIME part and does not rename a local source file.

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

    • setReplacePattern

      public void setReplacePattern​(String pattern, String replaceString)
      Defines a mail-merge replacement pair. pattern contains the pattern to find, and replaceString contains the replacement text.

      When the email is sent by a MailMan sending method, occurrences of pattern are replaced with replaceString. To define multiple replacement pairs, call this method once for each pair. The MailMan method RenderToMime also performs these replacements. Methods such as saveEml(String) and getMime() do not.

      pattern may occur in any header field and in either an HTML or plain-text body. Defining the pair does not immediately alter the stored body or headers; replacement occurs later during supported rendering or sending operations.

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

    • setSigningCert

      public void setSigningCert​(Cert cert)
      Sets the certificate in cert for creating a digital signature. Use the CreateCS, CertStore, and Cert classes to obtain a Cert object by locating a certificate in a certificate store or loading one from a file.

      cert must have access to its private key when signing occurs. Use setSigningCert2(Cert, PrivateKey) when the private key is supplied separately.

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

    • setSigningCert2

      public void setSigningCert2​(Cert cert, PrivateKey key)
      Explicitly sets the certificate in cert and the corresponding private key in key for sending digitally signed email.

      If cert already has access to its private key, it is usually sufficient to call setSigningCert(Cert). On Windows, Chilkat automatically searches the system certificate stores and Windows Protected Store for the corresponding certificate and private key. On macOS, Chilkat automatically searches the Keychain.

      In many cases, it is not necessary to set the signing certificate explicitly. Chilkat can automatically locate a certificate whose email address matches the email's From address, provided the certificate and private key are installed in a searchable certificate store or Keychain.

      Use this method when the private key is held separately from the certificate. cert and key must correspond to one another.

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

    • setTextBody

      public void setTextBody​(String bodyText, String contentType)
      Sets the body of the email and also sets the Content-Type header field of contentType. If the email is already multipart/alternative, an additional alternative with the indicated Content-Type will be added. If an alternative with the same Content-Type already exists, it is replaced.

      Use a textual MIME type such as text/plain or text/html. When building a plain-text/HTML pair, the dedicated alternative-body methods make the intended multipart/alternative structure clearer.

      Parameters:
      bodyText - the bodyText argument (not null)
      contentType - the contentType argument (not null)

    • toDsn

      public void toDsn​(String explanation, String statusFields, boolean headerOnly, Email dsnEmail)
      Creates a new Delivery Status Notification (DSN) email in the format specified by RFC 3464. The DSN email is generated in dsnEmail.

      The source email is not modified. Populate any additional sender or recipient fields on dsnEmail before sending the generated notification.

      Parameters:
      explanation - the explanation argument (not null)
      statusFields - the statusFields argument (not null)
      headerOnly - the headerOnly argument
      dsnEmail - the dsnEmail argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • toForward

      public void toForward​(Email fwdEmail)
      Creates an inline-forward email in fwdEmail based on this email.

      The source email is not modified. fwdEmail can be edited to add recipients, introductory text, or other forwarding details before sending.

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

    • toMdn

      public void toMdn​(String message, String statusFields, boolean headerOnly, Email mdn)
      Creates a new MDN (Message Disposition Notification) email in mdn using the format specified by RFC 3798.

      The source email is not modified. Populate any additional sender or recipient fields on mdn before sending the generated notification.

      Parameters:
      message - the message argument (not null)
      statusFields - the statusFields argument (not null)
      headerOnly - the headerOnly argument
      mdn - the mdn argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • toReply

      public void toReply​(Email reply)
      Generates a reply email in reply with updated header and body fields to enable sending as a reply. Note: Attachments are excluded from the reply, but attached messages are included. To exclude attached messages, call removeAttachedMessages() on the reply email object.

      The source email is not modified. reply can be edited to add introductory text, adjust recipients, or change reply behavior before sending.

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

    • uidlEquals

      public boolean uidlEquals​(Email e)
      Returns true if this email's UIDL equals the UIDL of the email passed in e.

      This comparison is meaningful for messages obtained through POP3. It does not compare IMAP UIDs, MIME Message-ID values, or message content.

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

    • unSpamify

      public void unSpamify()
      Unobfuscates emails by undoing what spammers do to obfuscate email. It removes comments from HTML bodies and unobfuscates hyperlinked URLs.

      This modifies the current email content. Make a copy first when the original HTML must be preserved for forensic or auditing purposes.

    • unpackHtml

      public void unpackHtml​(String unpackDir, String htmlFilename, String partsSubdir)
      Unpacks an HTML email into an HTML file and separate related files, such as images and style sheets. Links in the HTML are rewritten to reference the extracted files.

      unpackDir specifies the destination directory for the HTML file, htmlFilename specifies the HTML filename, and partsSubdir specifies the subdirectory beneath unpackDir where related files are written. Chilkat creates the related-files subdirectory when necessary.

      Example: If unpackDir is C:/test, htmlFilename is myEmail.html, and partsSubdir is images, Chilkat writes C:/test/myEmail.html and stores related files in C:/test/images.

      Note: Only related content physically contained in the email can be extracted. Images referenced by external web URLs are not downloaded.

      The extracted filenames originate from message content and should be treated as untrusted when processing email from unknown senders. The method operates on data already present in the email object.

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

    • unzipAttachments

      public void unzipAttachments()
      Unzips and replaces any Zip file attachments with the expanded contents. As an example, if an email contained a single Zip file containing 3 GIF image files as an attachment, then after calling this method the email would contain 3 GIF file attachments, and the Zip attachment would be gone.If an email contains multiple Zip file attachments, each Zip is expanded and replaced with the contents.

      This changes the attachment collection in memory; it does not extract files directly to a filesystem directory. Save the resulting attachments separately when files are required on disk.

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

    • useCertVault

      public void useCertVault​(XmlCertVault vault)
      Adds the XML certificate vault in vault to the object's internal certificate and private-key lookup sources for encryption, decryption, signing, and verification.

      Unlike AddPfxSourceData and addPfxSourceFile(String, String), only one XML certificate vault can be used. Each call replaces the vault supplied by the previous call, so only the most recent vault remains in use.

      vault becomes a lookup source for subsequent operations by this object. Adding it does not immediately sign, verify, encrypt, or decrypt anything.

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

    • zipAttachments

      public void zipAttachments​(String zipFilename)
      Replaces all the attachments of an email with a single Zip file attachment having the filename specified.

      The original attachments are removed from the in-memory email and their contents are placed into the new Zip attachment. Related items and attached emails are separate.

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