ASP Email Component

Docs: Certificate • Crypt • XML • ASP XML • Mail • S/MIME • Zip • SSL • RTC • Charset
CkStringArray • CkData • ChilkatCSP • MbRequest • AES Interop • EasyRSA • FTP

Help for Creating Objects in ASP

WebEmail
Represents a single email message including any attachments.

See Also: WebMailMan, WebBundle

WebEmail Properties

      Header Fields
      Encryption
      Digital Signatures
      Multipart Related/Alternative
      Mail Merge
      Distribution Lists
     Charset

Header Fields
[TOP]

Body As String read/write

The body of the email returned as a Unicode string. If the email contains both HTML and plain-text bodies, this will return the plain-text alternative. Use GetHtmlBody to retrieve the HTML body. If the email only contains an HTML body, and no plain-text body, this returns the HTML body. Note that this property always returns a Unicode string, so if the email body is internally stored in a multibyte character encoding such as utf-8, shift-jis, iso-8859-5, etc., it is automatically converted to Unicode and the converted string is returned. The internal representation is not affected.

EmailDate As Date read-only

The date and time in UTC/GMT standard. (for the local time, see LocalDate) This property is temporarily read-only because of certain technical problems. It will become read-write in a future release.

From As String read/write

The sender of the email, such as: "John Doe" <john.doe@mail.com>. The returned string is Unicode. If the From header field contained any Q or B encodings, these are automatically decoded and converted to Unicode.

FromName As String read/write

The name of the sender, such as: John Doe. The returned string is Unicode. If the header field contained any Q or B encodings, these are automatically decoded and converted to Unicode.

FromAddress As String read/write

The address of the sender, such as: john.doe@mail.com

LocalDate As Date read/write

The local date/time when the email was sent.

Mailer As String read/write

Identifies the mail program that sent the email. By default is set to "Chilkat Software SMTP"

NumAttachedMessages As Long read-only

The number of attached email messages contained in the email. Each attached message is a MIME sub-part with a content type of "message/rfc822".

NumAttachments As Long read-only

The number of attachments contained in the email.

NumBcc As Long read-only

The number of blind carbon-copy recipients.

NumCC As Long read-only

The number of carbon-copy recipients.

NumTo As Long read-only

The number of "to" recipients.

ReplyTo As String read/write

The email address used when a recipient replies. The returned string is Unicode. If the header field contained any Q or B encodings, these are automatically decoded and converted to Unicode.

ReturnReceipt As Long read/write

When set to 1, causes a return receipt to be requested when the email is sent. The default is 0.

Size As Long read-only

The size in bytes of the email, including all parts and attachments.

Subject As String read/write

The subject of the email returned as a Unicode string. If the header field contained any Q or B encodings, these are automatically decoded and converted to Unicode.

RawHeader As String read/write

The raw header containing all the email fields not explicitly represented by properties or methods. Only emails retrieved from a POP3 mailbox will have a raw header. (as opposed to emails constructed from scratch by setting properties and calling methods)

Uidl As String read-only

This is the unique ID assigned by the POP3 server. Emails can be retrieved or deleted from the POP3 server via the UIDL. The header field for this property is "X-UIDL".

Encryption
[TOP]

Click HERE for additional information regarding S/MIME encryption.

IMPORTANT: Click HERE for important information regarding Warning Dialogs displayed by Microsoft Windows when directly or indirectly accessing private keys.

Decrypted As Boolean read-only

If the email was received with encrypted parts, either in whole or part, this property is TRUE if all encrypted parts were successfully decrypted. (The ChilkatMail component automatically decrypts messages when they are received.)

EncryptedBy As String read-only

If the email was received in encrypted format, this property contains the details of the certificate used to encrypt the email.

ReceivedEncrypted As Boolean read-only

True if this email was originally received with encryption.

SendEncrypted As Boolean read/write

Set this property to true to send an encrypted email. If this property and SendSigned are both true, the email will be sent both encrypted and signed.

Digital Signatures
[TOP]

Click HERE for additional information regarding S/MIME encryption.

IMPORTANT: Click HERE for important information regarding Warning Dialogs displayed by Microsoft Windows when directly or indirectly accessing private keys.

ReceivedSigned As Boolean read-only

True if this email was originally received with an attached digital signature.

SendSigned As Boolean read/write

Set this property to true to send a digitally signed email. If this property and SendEncrypted are both true, the email will be sent both encrypted and signed.

SignaturesValid As Boolean read-only

If the email was received with a digital signature, this property is TRUE if all signatures were verified to be valid. (The ChilkatMail automatically verifies digital signatures when an email arrives.)

SignedBy As String read-only

If the email was digitally signed, this property contains the details of the signer.

Multipart Related/Alternative
[TOP]

NumAlternatives As Long read-only

The number of alternative bodies present in the email. An email that is not "multipart/alternative" will return 0 alternatives. An email that is "multipart/alternative" will return a number greater than or equal to 1.

NumRelatedItems As Long read-only

The number of related items present in this email. Related items are typically image files (JPEGs or GIFs) that are included with HTML formatted messages with internal "CID" hyperlinks.

Mail Merge
[TOP]

NumReplacePatterns As Long read-only

The number of replacement patterns defined. This is a mail-merge feature.

Distribution Lists
[TOP]

FileDistList As String read/write

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. There is no need to add "To", "CC", or "Bcc" recipients if this property is set.

Setting this property is equivalent to adding a "CKX-FileDistList" header field to the email. Chilkat Mail 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, Chilkat Mail 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 ChilkatMailMan.SendIndividual property).

Charset
(BACK)

HtmlCharset As String read/write

The character encoding of the HTML email body, such as utf-8, iso-8859-1, shift-jis, big5, etc. To convert the HTML body to another character encoding, simply set this property to the name of a different charset. If the conversion fails because characters in the HTML source have no representation in the target encoding, then nothing will happen and the HtmlCharset property will remain unchanged. The conversion not only converts the HTML character data, but adds or changes the HTML meta tag that specifies the charset within the HTML.(BACK)

PlainTextCharset As String read/write

The character encoding of the plain-text email body, such as utf-8, iso-8859-1, shift-jis, big5, etc. To convert the plain-text body to another character encoding, simply set this property to the name of a different charset. If the conversion fails because characters in the source have no representation in the target encoding, then nothing will happen and the PlainTextCharset property will remain unchanged. (BACK]

Error Logging
(BACK)

ErrorLogHtml As String read-only

Error information for the last method call in HTML format with <br> line breaks.(BACK)

WebEmail Methods

Clone, Reply, Forward
Adding Recipients
Attachments
Multipart-Related Items
HTML Email
XML and MIME Import/Export
Multipart Alternative
Getting/Setting Header Fields
Mail Merge
International Character Encoding (Charsets)
Secure Email

GetInstanceLog() As String

Returns the log in XML format for this object instance. The log is cleared when this method is called.

Clone, Reply, Forward
[TOP]

Clone() As WebEmail

Creates an identical duplicate WebEmail object.

CreateForward() As WebEmail

Returns a copy of the WebEmail object with the body and header fields changed so that the newly created email can be forwarded. After calling CreateForward, simply add new recipients to the created email, and call ChilkatMailMan.SendEmail.

CreateReply() As WebEmail

Returns a copy of the WebEmail object with the body and header fields changed so that the newly created email can be sent as a reply. After calling CreateReply, simply prepend additional information to the body, and call ChilkatMailMan.SendEmail.

Adding Recipients
[TOP]

AddBcc(name As String, address As String) As Boolean

Adds a recipient to the blind carbon-copy list. address is required, but name may be empty. Returns True if successful.

AddCC(name As String, address As String) As Boolean

Adds a recipient to the carbon-copy list. address is required, but name may be empty. Returns True if successful.

AddTo(name As String, address As String) As Boolean

Adds a recipient to the "to" list. address is required, but name may be empty. Returns True if successful. Emails that have no "To" recipients will be sent to <undisclosed-recipients>.

AddMultipleBcc(commaSeparatedAddresses As String) As Boolean

Adds multiple recipients to the blind carbon-copy list. The parameter is a string containing a comma separated list of full email addresses. Returns True if successful.

AddMultipleCC(commaSeparatedAddresses As String) As Boolean

Adds multiple recipients to the carbon-copy list. The parameter is a string containing a comma separated list of full email addresses. Returns True if successful.

AddMultipleTo(commaSeparatedAddresses As String) As Boolean

Adds multiple recipients to the "to" list. The parameter is a string containing a comma separated list of full email addresses. Returns True if successful.

ClearBcc()

Clears the list of blind carbon-copy recipients.

ClearCC()

Clears the list of carbon-copy recipients.

ClearTo()

Clears the list of "to" recipients.

GetBcc(index As Long) As String

Returns a blind carbon-copy recipient. Indexing begins at 0.

GetCC(index As Long) As String

Returns a carbon-copy recipient. Indexing begins at 0.

GetTo(index As Long) As String

Returns a "to" recipient. Indexing begins at 0.

Attachments
[TOP]

AddDataAttachment(attachmentData as Variant, fileName As String) As String

Adds a memory buffer as an attachment to the email. The fileName is passed in as the name of the file that would get created if the recipient saves the attachment to disk. Returns the MIME content-type of the attachment, which is inferred based on the filename extension.

AddFileAttachment(fileName As String) As String

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.

AddFileAttachment2(fileName As String, contentType As String)

Same as AddFileAttachment, but the content type can be explicitly specified.

DropAttachments()

Removes all attachments from the email.

DropSingleAttachment(index As Long) As Boolean

Drops a single attachment from the email. Returns True if successful. Indexing begins at 0.

GetAttachedMessage(index As Long) As WebEmail

Retrieves one of the emails (if any) attached to the calling email object. Indexing begins at 0. Returns the attached email as a full email object which may contain additional attached emails.

GetAttachmentContentID(index As Long) As String

Retrieves the contentID of an attachment. Indexing begins at 0.

GetAttachmentData(index As Long) As Variant

Retrieves an attachment's binary data. Indexing begins at 0.

GetAttachmentFilename(index As Long) As String

Retrieves an attachment's filename. Indexing begins at 0.

GetAttachmentSize(index As Long) As String

Retrieves an attachment's size in bytes. Indexing begins at 0.

GetAttachmentString(index As Long) As String

Retrieves an attachment's data as a String. All CRLF sequences will be translated to single newline characters. Indexing begins at 0.

GetAttachmentStringCrLf(index As Long) As String

Retrieves an attachment's data as a String. All end-of-lines will be translated to CRLF sequences. Indexing begins at 0.

SaveAllAttachments(directory As String) As Boolean

Save all of this email's attachments to a directory. Return True if successful.

SaveAttachedFile(index As Long, directory As String) As Boolean

Save one of the email's attachments to a directory. Return True if successful. Indexing begins at 0.

SetAttachmentFilename(index As Long, fileName As String) As Boolean

Change the filename of one of the email attachments. Return True if successful. Indexing begins at 0.

Multipart-Related Items
[TOP]

GetRelatedContentID(index As Long) As String

Retrieves the contentID of a related item. Indexing begins at 0.

GetRelatedData(index As Long) As Variant

Retrieves a related item's binary data. Indexing begins at 0.

GetRelatedFilename(index As Long) As String

Retrieves a related item's filename. Indexing begins at 0.

GetRelatedString(index As Long) As String

Retrieves a related item's data as a String. All CRLF sequences will be translated to single newline characters. Indexing begins at 0.

GetRelatedStringCrLf(index As Long) As String

Retrieves a related item's data as a String. All end-of-lines will be translated to CRLF sequences. Indexing begins at 0.

Other methods: AddRelatedContent, SaveRelatedItem

HTML Email
[TOP]

AddRelatedContent(filename As String) as String

Adds the contents of a file to the email and returns the Content-ID. Emails formatted in HTML can include images with this call and internally reference the image through a "cid" hyperlink. (ChilkatMail fully supports the MHTML standard.) See the example programs on the Chilkat website.

AddRelatedData(data As Variant, filename As String) as String

Adds the contents of a data buffer to the email and returns the Content-ID. This data buffer would typically contain image data in GIF or JPG format. Although the data comes from an in-memory data buffer, a fictional filename must be provided to (1) determine the format of the data, and (2) determine the filename if the related data item was to be saved to disk and HTML reconstructed.

AddHtmlAlternativeBody(body As String)

Sets the HTML body of the email. Use this method if there will be multiple versions of the body, but in different formats, such as HTML and plain text. Otherwise, set the body by calling the SetHtmlBody method.

GetHtmlBody() As String

Returns the body that has the "text/html" content type. The HTML is returned as a Unicode string.

SaveRelatedItem(index as Long, directory As String) as Boolean

Saves a related item to a file in a directory. The NumRelatedItems property contains the number of related items contained in the email. The function returns TRUE if successful. Indexing begins at 0.

SetHtmlBody(body As String)

Sets the Body property, and sets the email's content type to "text/html". Use this method if the body is HTML, and if there are no other alternative bodies.

XML, EML and MIME Import/Export
[TOP]

GetMime() As String

Return an MIME representation of the email.

GetXml() As String

Return an XML representation of the email.

SaveXml(filename As String)

Save the email in XML format.

Multipart/Alternative
[TOP]

AddPlainTextAlternativeBody(body As String)

Sets the plain-text body of the email. Use this method if there will be multiple versions of the body, but in different formats, such as HTML and plain text. Otherwise, simply set the Body property.

GetAlternativeBody(index As Long) As String

Returns the Nth alternative body. The NumAlternatives property tells the number of alternative bodies present. Use the GetHtmlBody and GetPlainTextBody methods to easily get the HTML or plain text alternative bodies. Indexing begins at 0.

GetAlternativeContentType(index As Long) As String

Returns the content type of the Nth alternative body. The NumAlternatives property tells the number of alternative bodies present. Indexing begins at 0.

GetPlainTextBody() As String

Returns the body having the "text/plain" content type. The text is returned as a Unicode string.

Getting/Setting Header Fields
[TOP]

AddHeaderField(fieldName As String, fieldValue As String) As Long

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.

GetHeaderFieldName(index As Long) As String

Return the name of the Nth header field. The NumHeaderFields() method can be used to get the number of header fields. The GetHeaderField() method can be used to get the value of the field given the field name. Indexing begins at 0.

GetHeaderField(fieldName As String) As String

Retrieves the value of a header field.

NumHeaderFields() As Long

Return the number of header fields present in the email.

RemoveHeaderField(fieldName As String)

Removes all occurances of a header field, if any exist.

Mail Merge
[TOP]

GetReplacePattern(index As Long) As String

Gets one of the replacement patterns, if any have been defined. This is a mail-merge feature. Indexing begins at 0.

GetReplaceString(index As Long) As String

Gets one of the replacement strings, if any replacment patterns have been defined. This is a mail-merge feature. Indexing begins at 0.

GetReplaceString2(pattern As String) As String

Gets one of the replacement strings, if any replacment patterns have been defined. This is a mail-merge feature.

SetReplacePattern(pattern As String, replaceString As String) As Boolean

Define a replacement pattern. When the mailman sends this email, it will first find all occurances of each pattern and substitute the replacment string. The replacement patterns are persisted with the email when saved to a Zip archive.

International Character Encoding (Charsets)
(BACK)

BEncodeBytes(byteData As Variant, charset As String) As String

Takes a byte array of multibyte (non-Unicode) data and returns a Unicode B-Encoded string.
(BACK)

BEncodeString(unicodeString As String, charset As String) As String

Takes a Unicode string, converts it to the charset specified in the 2nd parameter, B-Encodes the converted multibyte data, and returns the encoded Unicode string.
(BACK)

EncodeHeader(charset As String)

This is a smart and powerful method. It converts all the appropriate email header fields to the specified charset. Fields that cannot be converted because there is no representation in the target charset are left unchanged. This method will convert the From, To, CC, Subject, and ReplyTo fields. For address fields such as To, CC, etc., the name part of the address is Q (or B) encoded but the address part is not. A simple way of converting an entire email to another charset is to call EncodeHeader to convert the header fields, and then set the HtmlCharset and PlainTextCharset properties to convert the email bodies.
(BACK)

GetMbHeaderField(fieldName As String, htmlEncode as Long) As Variant

Returns a header field's data in a byte array. If the field was Q or B encoded, this is automatically decoded, and the raw bytes of the field are returned. If htmlEncode is 1, the returned data is also HTML-encoded. Call GetHeaderField to retrieve the header field as a Unicode string.
(BACK)

GetMbHtmlBody(convertToCharset as String) As Variant

Returns the HTML body converted to a specified charset. If no HTML body exists, the returned byte array is empty. The returned data will be such that not only is the character data converted (if necessary) to the convertToCharset, but the HTML is edited to add or modify the META tag that specifies the charset within the HTML.
(BACK)

GetMbPlainTextBody(convertToCharset as String, htmlEncode as Long) As Variant

Returns the plain-text body converted to a specified charset. If htmlEncode is 1, the returned data is also HTML-encoded. The return value is a byte array containing multibyte character data.
(BACK)

QEncodeBytes(byteData As Variant, charset As String) As String

Takes a byte array of multibyte (non-Unicode) data and returns a Unicode Q-Encoded string.
(BACK)

QEncodeString(unicodeString As String, charset As String) As String

Takes a Unicode string, converts it to the charset specified in the 2nd parameter, Q-Encodes the converted multibyte data, and returns the encoded Unicode string.
(BACK)

SetMbHtmlBody(charset as String, byteData As Variant)

Sets the HTML email body from a byte array containing character data in the specified character set. This method also updates the email "content-type" header to properly reflect the content type of the body.
(BACK)

SetMbPlainTextBody(charset as String, byteData As Variant)

Sets the plain-text email body from a byte array containing character data in the specified character set. This method also updates the email "content-type" header to properly reflect the content type of the body.
(BACK)

Secure Email
[TOP]

GetEncryptedByCert() As ChilkatCert

Returns the certificate associated with a received encrypted email. (BACK)

GetSignedByCert() As ChilkatCert

Returns the certificate associated with a received signed email. (BACK)

SetCSP(csp As ChilkatCSP)

Sets the encryption and digital signature preferences for this email. The SendSigned and SendEncrypted properties still need to be set to cause an email to be sent encrypted or signed, but the ChilkatCSP object will control the Cryptographic Service Provider used, the key container within the CSP to be used, and the encryption/hash algorithms. (BACK)

SetEncryptCert(cert As ChilkatCert)

Explicitly sets the certificate to be used for encryption when sending encrypted (S/MIME) emails. (BACK)

SetSigningCert(cert As ChilkatCert)

Explicitly sets the certificate to be used for signing when sending digitally signed (S/MIME) emails. (BACK)

Other
[TOP]

GetFileContent(filename As String) As String

Reads a file and returns the contents as a String. This is here purely for convenience.

HasHtmlBody( ) As Long

Returns 1 if the email has an HTML body, otherwise returns 0.

HasPlainTextBody( ) As Long

Returns 1 if the email has a plain-text body, otherwise returns 0.

IsMultipartReport( ) As Long

Returns 1 if the email has a content-type of multipart/report, which is the content-type for bounced email notifications.