|
Codestone Ltd Internet Mail Client Control Library © Codestone Ltd 1996-2003 |
|
Welcome to the Codestone Internet Mail Client Control Library (CSMail), we hope you will find the library to be a rapid and painless way to add email functionality to your application. With CSMail you can send and receive email using SMTP and POP3 – the standard email protocols on the Internet. Your emails can be as simple as a plain text message or as complex as a richly formatted HTML message with embedded stationary – and you can add as many attachments to the mail as you please. By utilising ActiveX COM technology the CSMail library is available to programmers working in Visual Basic ®, Visual C++ ®, Microsoft® Office, ASP on IIS, the Windows Scripting Host and many more environments. Our customers have used CSMail to great effect in applications including ISS Web-Mail sites, email gateways and bespoke email clients.
|
Message Object Developer’s Reference
Section Object Developer’s Reference
SMTPClient Object Developer’s Reference
POP3 Client Developer’s Reference
FileClient Object Developer’s Reference
ProxyInfo Objects Developer’s Reference
Appendix B CSMail Error Numbers and Messages
Declaration: SaveToFile(Filename as String)
|
Filename |
The full pathname of the destination file. |
Saves the entire message structure, including any attachments, to a disk file. This method saves the message in an optimised format that can only be read by the LoadFromFile method.
There is no return value from this method. If any error occurs while saving the message an error will be raised and should be handled through the VB/VBA/VBScript On Error mechanism.
Declaration: LoadFromFile(Filename as String)
|
Filename |
The full pathname of the source file. |
Loads the entire message structure, including any attachments, from a disk file. This method can only load messages in the optimised format written by the SaveToFile method.
There is no return value from this method. If any error occurs while loading the file an error will be raised and should be handled through the VB/VBA/VBScript On Error mechanism.
Declaration: Subject as String
The subject of the message. This property corresponds to the MIME ‘Subject’ header field.
MyMsg.Subject="Medical Officer's Report
"
And
myMsg.Header("Subject")="Medical Officer's Report"
Are functionally equivalent.
MyMsg.Subject="Medical Officer's Report"
Declaration: From as AddressList
The originators of the message.
This read/write property is a one-based collection of address. Developers will typically set the elements of the list before sending a message with the SMTPClient Object - or read the elements of the array after receiving a message with the POP3Client Object.
This property corresponds to the MIME ‘From’ header field:
MyMsg.From(1)=”bones@enterprise.fed”
MyMsg.From(2)=”spock@enterprise.fed”
And
myMsg.Header("From")=”bones@enterprise.fed,spock@enterprise.fed”
Are functionally equivalent.
Addresses should be added to the list in consecutive order, starting at an index of one.
Care must be taken to ensure that a legal combination of 'From' and 'Sender' fields exists before the message is sent otherwise the SMTPClient will report an error - this table shows the allowed options.
|
Number of ‘From’ addresses |
Number of ‘Sender’ Addresses |
Notes |
|
0 |
1 |
Sender is compulsory if there are no 'From' addresses. |
|
1 |
0 or 1 |
Sender is optional if there is exactly one 'From' address. |
|
>1 |
1 |
Sender is compulsory if there are more than one 'From' addresses. |
The following formats are allowed for the specification of the From property:
|
Type |
Example |
|
Mailbox |
|
This property also supports the standard collection methods and properties (Add, Remove , Count and Item).
MyMsg.From(1)="bones@enterprise.fed"
Declaration: Sender as AddressList
The sender of the message.
This read/write property is a one-based collection of address. Developers will typically set the elements of the list before sending a message with the SMTPClient Object - or read the elements of the array after receiving a message with the POP3Client Object.
This property corresponds to the MIME ‘Sender’ header field:
MyMsg.Sender(1)=”bones@enterprise.fed”
And
myMsg.Header("Sender")=”bones@enterprise.fed”
Are functionally equivalent.
See the From Property for a description of the legal formats for email addresses for this property and for legal combinations of From and Sender addresses.
MyMsg.Sender(1)="uhura@enterpise.fed"
Declaration: ReplyTo as AddressList!JumpContext(D:\dev\Controls\CSMail\Debug\CSMail.hlp,250)
The address to which replies should be sent.
This read/write property is a one-based collection of address. Developers will typically set the elements of the list before sending a message with the SMTPClient Object - or read the elements of the array after receiving a message with the POP3Client Object.
This property corresponds to the MIME ‘Reply-To’ header field:
MyMsg.ReplyTo(1)=”bones@enterprise.fed”
And
myMsg.Header("Reply-To")=”bones@enterprise.fed”
Are functionally equivalent.
Addresses should be added to the list in consecutive order, starting at an index of one.
The following formats are allowed for the specification of the ReplyTo property:
|
Type |
Example |
|
Mailbox |
|
|
Group |
captains : kirk@enterprise.fed, janeway@voyager.fed; |
This property also supports the standard collection methods and properties (Add, Remove , Count and Item) together with the Visual Basic for .. each construct.
MyMsg.ReplyTo(1)="bones@enterprise.fed"
Declaration: To as AddressList
The primary recipients of the message.
This read/write property is a one-based collection of address. Developers will typically set the elements of the list before sending a message with the SMTPClient Object - or read the elements of the array after receiving a message with the POP3Client Object.
This property corresponds to the MIME ‘To’ header field:
MyMsg.To(1)=”bones@enterprise.fed”
And
myMsg.Header("To")=”bones@enterprise.fed”
Are functionally equivalent.
Addresses should be added to the list in consecutive order, starting at an index of one.
The following formats are allowed for the specification of the To property:
|
Type |
Example |
|
Mailbox |
|
|
Group |
captains : kirk@enterprise.fed, janeway@voyager.fed; |
This property also supports the standard collection methods and properties (Add, Remove , Count and Item).
MyMsg.To(1)="bones@enterprise.fed"
Declaration: CC as AddressList
The secondary (CC) recipients of the message. This property corresponds to the MIME ‘CC’ header field.
Addresses should be added to the list in consecutive order, starting at an index of one.
See the To Property for a description of the legal formats for email addresses for this property.
This property also supports the standard collection methods and properties (Add, Remove , Count and Item).
MyMsg.CC(1)="bones@enterprise.fed"
Declaration: BCC as AddressList
The tertiary (BCC) recipients of the message. The message is delivered to these recipients but is not included in the list of recipients.
This property corresponds to the MIME ‘BCC’ header field.
Addresses should be added to the list in consecutive order, starting at an index of one.
See the To Property for a description of the legal formats for email addresses for this property.
This property also supports the standard collection methods and properties (Add, Remove , Count and Item).
MyMsg.BCC (1)="bones@enterprise.fed"
Declaration: Sections as SectionCollection!JumpContext(D:\dev\Controls\CSMail\Debug\CSMail.hlp,350)
The sections (parts) of the message.
Each part of a message is held in a separate section. Simple messages may contain only a single section with a textual body, more complex messages may contain several sections including, for example, text and images.
Sections should be added to the list in consecutive order, starting at an index of one.
See the Sections Object reference for a full description of the Section Object.
This property also supports the standard collection methods and properties (Add, Remove , Count and Item).
MyMsg.Sections(1).Body="Its life Jim, but not as we know it."
MyMsg.Sections(2).AttachBodyFromFile("tribbles.jpg")
Declaration: Header as Header
The MIME Header for the message. This property provides access to the raw MIME header fields for the message.
The fields in the MIME header are automatically maintained as the properties of the object are changed and most applications will not need to access the headers directly.
The Header property is implemented as dictionary -type collection of strings and is keyed by the field name.
MyMsg.Sections(1).Header("Content-Type")="multipart/alternative"
Declaration: Tag as String
A user defined string value
Declaration: UIDL as String
The message UIDL, as reported bye the POP3 server.
This property is valid only for messages received with the POP3Client Object.
Declaration: ByteSize as long
The message byte size, as reported by a POP3 server.
This property is valid only for messages received with the POP3Client Object.
Declaration: Ordinal as long
The ordinal number of the message on the POP3 server.
This property is valid only for messages received with the POP3Client Object.
Declaration: AttachBodyFromFile(Filename as String)
|
Filename |
The full pathname of the source file. |
Description
Sets the section body to the contents of a file and marks the section as an attachment.
There is no return value from this method. If any error occurs while attaching the file an error will be raised and should be handled through the VB/VBA/VBScript On Error mechanism.
Declaration: ReadBodyFromFile(Filename as String)
|
Filename |
The full pathname of the source file. |
Description
Sets the section body to the contents of a disk file and marks the section as ‘inline’.
There is no return value from this method. If any error occurs while reading the file an error will be raised and should be handled through the VB/VBA/VBScript On Error mechanism.
Declaration: WriteBodyToFile(Filename as String)
|
Filename |
The full pathname of the destination file. |
Description
Writes the section body to a disk file.
There is no return value from this method. If any error occurs while writing the file an error will be raised and should be handled through the VB/VBA/VBScript On Error mechanism.
Declaration: Body as String
Description
The section body.
This read/write property allows access to the text or data held in the body of the section - this property always reflects the native (un-encoded) form of the data - the data is automatically encoded when it is sent by SMTP client and decoded when it is received by the POP3 Client.
The Body property can only be used safely for accessing text content - binary data may be subject to undesired transformations - this is due to the need to convert from the character set used in message transmission to the Unicode character set used by OLE automation. The ReadBodyFromFile, AttachBodyFromFile and WriteBodyToFile methods provide a convenient means to transfer arbitrary binary data to and from disk files. The BodyBinary property provides a convenient method to access the binary contents of the section.
MyMsg.Sections(1).Body="Its life Jim, but not as we know it."
Declaration: BodyBinary as Variant
Comaptability: V 1.5.5 and greater
Description
The binary contents of the section body.
This read/write property allows access to the binary data held in the body of the section - this property always reflects the native (un-encoded) form of the data - the data is automatically encoded when it is sent by SMTP client and decoded when it is received by the POP3 Client.
The BodyBinary property can be used to safely access binary data without the undesirable transformations which conversion to and from unicode can produce.
Response.ContentType = section.Header("Content-Type")
Response.addHeader "content-disposition", "filename=" & section.filename
response.binarywrite (section.bodybinary)
Declaration: Header as Header
The MIME Header for the section.
This property provides access to the raw MIME header fields for the message.
Each section has it's own header which contains the fields which describe the content and type of the section.
The fields in the MIME header are automatically maintained as the properties of the object are changed and most applications will not need to access the headers directly.
The Header property is implemented as dictionary-type collection of strings and is keyed by the field name.
myMsg.Header("Subject")="Message from Starfleet Headquarters"
Declaration: Sections as SectionCollection
The sub-sections (parts) of the section
RFC 1341 allows for multipart messages to contain nested multipart sections. This is supported by the Message Object Model and implemented in the SMTP and POP3 clients.
Sections should be added to the list in consecutive order, starting at an index of one.
See Example 9 Nested multipart messages for an example of creating nested multipart messages.
Declaration: CharacterSet as String
Description
The character set assigned to the section.
This property corresponds to the charset parameter of the RFC 1341 Content-Type field.
This property is set automatically by the control when either creating a new section or retrieving a message with the POP3Client Object. Applications may wish to examine this property after a message has been received in order to take appropriate action. Only advanced applications should attempt to set this property before sending a message.
Declaration: Disposition as String
Description
The disposition type assigned to the section
This property relates to the disposition parameter of the RFC 2183 Content-Disposition field.
This property is set automatically by the control when either creating a new section or retrieving a message with the POP3Client Object. Applications may wish to examine this property after a message has been received in order to take appropriate action. Only advanced applications should attempt to set this property before sending a message.
In general the Disposition property will be either 'inline' or ‘attachment’ indicating a section which is to be included in the body or attached respectively.
Declaration: Encoding as String
Description
The transfer encoding scheme of the section
The encoding schema of the body. May be 7bit, 8bit, base64 or quoted-printable.
This property is set automatically by the control when either creating a new section or retrieving a message with the POP3Client Object. Applications may wish to examine this property after a message has been received in order to take appropriate action. Only advanced applications should attempt to set this property before sending a message.
Declaration: Filename as String
Description
The filename assigned to the section, may be empty
This property relates to the filename parameter of the RFC 2183 Content-Disposition field.
This property is set automatically by the control when either creating a new section or retrieving a message with the POP3Client Object. Applications may wish to examine this property after a message has been received in order to take appropriate action. Only advanced applications should attempt to set this property before sending a message.
Declaration: Type as String
Description
The MIME type assigned to the section
This property relates to the type component of the RFC 1341 Content-Type field.
This property is set automatically by the control when either creating a new section or retrieving a message with the POP3Client Object. Applications may wish to examine this property after a message has been received in order to take appropriate action. Only advanced applications should attempt to set this property before sending a message.
Declaration: SubType as String
Description
The MIME sub-type assigned to the section
This property relates to the sub-type component of the RFC 1341 Content-Type field.
This property is set automatically by the control when either creating a new section or retrieving a message with the POP3Client Object. Applications may wish to examine this property after a message has been received in order to take appropriate action. Only advanced applications should attempt to set this property before sending a message.
LastServerResponseCode Property
LastServerResponseString Property
Declaration: SetProxyInfo(ProxyInfo as Object)
|
ProxyInfo |
An object providing information required to connect to a server through a proxy server. Currently allowed objects are: o SOCK4ProxyInfo object o SOCK5ProxyInfo object o POP3ProxyInfo object o SMTPProxyInfo object |
Informs the SMTPClient or POP3Client object about the proxy/firewall connection required by the caller.
There is no return value from this method. If any error occurs while a message is being sent an error will be raised and should be handled through the VB/VBA/VBScript On Error mechanism.
See the examples for the SOCK4ProxyInfo, SOCK5ProxyInfo, POP3ProxyInfo and SMTPProxyInfo objects
Declaration: Connect(Host as String,[Port as long])
|
Host |
The address of the SMTP smart host. The host may be specified as a dotted IP address (e.g. 127.0.0.1) or as a host name (e.g. mail.myisp.com) |
|
Port |
The port on which to make the connection, if Port is not specified the connection will be made on port 25, the default for the SMTP protocol. |
Attempts to connect to the named SMTP server using the specified port.
There is no return value from this method. If any error occurs during the connection process an error will be raised and should be handled through the VB/VBA/VBScript On Error mechanism.
During the connection process the object will:
· Resolve the host name and attempt to create a TCP connection to the host.
· If the connection is successful the object will attempt to issue the preliminary HELO SMTP command and process the response.
Declaration: ConnectESMTP(Host as String,[Username as String],[Password as String],[Auth(=LOGIN) as String],[Port as long])
|
Host |
The address of the SMTP smart host. The host may be specified as a dotted IP address (e.g. 127.0.0.1) or as a host name (e.g. mail.myisp.com) |
|
Username |
The authentication username |
|
Password |
The authentication password |
|
Auth |
The authentication method. Currently only LOGIN is supported |
|
Port |
The port on which to make the connection, if Port is not specified the connection will be made on port 25, the default for the SMTP protocol. |
Attempts to connect to the named ESMTP server using the specified authentication details and port.
There is no return value from this method. If any error occurs during the connection process an error will be raised and should be handled through the VB/VBA/VBScript On Error mechanism.
During the connection process the object will:
· Resolve the host name and attempt to create a TCP connection to the host.
· If the connection is successful the object will attempt to issue the preliminary ESMTP EHLO and AUTH commands.
Declaration: Close
Close the connection to the remote server
There is no return value from this method. If any error occurs during the disconnection process an error will be raised and should be handled through the VB/VBA/VBScript On Error mechanism.
During the disconnection process the object will:
· Issue the SMTP QUIT command
· Close the TCP connection and release the socket.
Declaration: SendMessage(Message as Message)
|
Message |
A message object. See the Message Object reference for details of the Message Object. |
Send a message though the SMTP server. Connect () or ConnectESMTP () must be called before this method is called. SendMessage () may be called repeatedly before Close () is called if there are multiple messages to be sent.
There is no return value from this method. If any error occurs while a message is being sent an error will be raised and should be handled through the VB/VBA/VBScript On Error mechanism.
While sending a message the object will:
· Issue the SMTP RCPT TO commands for each address in the Message Object’s To and CC property array. RCPT TO commands are not issued for addresses in the BCC property array.
· Issue an SMTP MAIL FROM command for the appropriate originator field. If there is a single address in the Message Object’s From property array then that address will be used. If there is more than one address in the Message Object’s From property array then there must be a single Sender address.
· Issue an SMTP DATA command and transmit the message body to the SMTP server, encoding attachments appropriately if required.
Declaration: SendMessageEx(Message as IMessage, EnvelopeTo as String [ ,EnvelopeFrom as String])
|
Message |
A message object. See the Message Object reference for details of the Message Object. |
|
EnvelopeTo |
The addresses to which the messages should be sent. |
|
EnvelopeFrom |
The address from which the message should be sent. |
Send a message though the SMTP server. Connect () or ConnectESMTP () must be called before this method is called. SendMessageEx () may be called repeatedly before Close () if there are multiple messages to be sent.
There is no return value from this method. If any error occurs while a message is being sent an error will be raised and should be handled through the VB/VBA/VBScript On Error mechanism.
While sending a message the object will:
· Issue the SMTP RCPT TO commands for each address in the list provided in the EnvelopeTo parameter.
· Issue an SMTP MAIL FROM command for the address in the EnvelopeFrom parameter. There should be exactly one address in this list. If there is not exactly one address in the list an error will be generated.
Issue an SMTP DATA command and transmit the message body to the SMTP server, encoding attachments appropriately if required.
Declaration: LastServerResponseCode as String
The last SMTP response code from the remote server
The property represents the numeric portion of the SMTP server’s response (the ‘response code’) to the last command issued. Sophisticated applications may wish to examine this property in order to take corrective actions after an SMTP Error (Error number 80040206 or 80040204) has occurred. Developers should refer to Appendix E of RFC 821 for a detailed discussion of the theory of SMTP reply codes.
Declaration: LastServerResponseString as String
The last SMTP response from the remote server
The property contains the SMTP server’s response to the last command issued. Applications may wish to log or report this string to the user after an SMTP Error (Error number 80040206 or 80040204) has occurred.
Declaration: LastSocketError as String
The last error reported by the socket layer
The property contains a description of the last error reported by the Winsock DLL. Applications may wish to inspect this property after a Socket Error (Error number 80040204 or 80040207) has occurred.
POP3Client.POP3QUIT Method (Low Level)
POP3Client.LastServerResponseString Property
Declaration: SetProxyInfo(ProxyInfo as Object)
|
ProxyInfo |
An object providing information required to connect to a server through a proxy server. Currently allowed objects are: o SOCK4ProxyInfo object o SOCK5ProxyInfo object o POP3ProxyInfo object o SMTPProxyInfo object |
Informs the SMTPClient or POP3Client object about the proxy/firewall connection required by the caller.
There is no return value from this method. If any error occurs while a message is being sent an error will be raised and should be handled through the VB/VBA/VBScript On Error mechanism.
See the examples for the SOCK4ProxyInfo, SOCK5ProxyInfo, POP3ProxyInfo and SMTPProxyInfo objects.
Declaration: Connect(Host as String, Username as String, Password as String,[Port as long])
|
Host |
The address of the POP3 server. The host may be specified as a dotted IP address (e.g. 127.0.0.1) or as a host name (e.g. mail.myisp.com) |
|
Username |
The authentication username |
|
Password |
The authentication password |
|
Port |
The port on which to make the connection, if Port is not specified the connection will be made on port 110, the default for the POP3 protocol. |
Attempts to connect to the named POP3 server using the specified port. After a successful connection is established the Messages collection property will contain an empty Message Object for each message on the maildrop, applications should subsequently call RetrieveMessages (), POP3RETR () or POP3TOP() to retrieve full or partial copies of the message.
There is no return value from this method. If any error occurs during the connection process an error will be raised and should be handled through the VB/VBA/VBScript On Error mechanism.
During the connection process the object will:
· Resolve the host name and attempt to create a TCP connection to the host.
· If the connection is successful the object will attempt to issue the preliminary POP3 USER and PASS command
· If the authentication parameters are accepted the object issues a STAT command to establish the number of the messages in the maildrop and the total size of the messages. The object then populates the Messages collection property with an empty Message Object for each message.
· Issue a POP3 LIST command and set the ByteSize property of each Message Object in the collection appropriately.
Declaration: Close([CommitChanges(=True) as long])
|
CommitChanges |
See description below. |
Close the connection to the remote server. If CommitChanges is True (the default) then messages marked for deletion (see RetrieveMessages () and POP3DELE ()) are removed from the server, otherwise messages marked for deletion are not removed.
There is no return value from this method. If any error occurs during the disconnection process an error will be raised and should be handled through the VB/VBA/VBScript On Error mechanism.
During the disconnection process the object will:
· Issue the POP3 RSET command if changes are not to be commited
· Issue the POP3 QUIT command
· Close the TCP connection and release the socket.
Declaration: RetrieveMessages([Index(=0) as long],[Lines(=0) as long])
|
Index |
Message Index. The default is all messages on the maildrop/ |
|
Lines |
Number of lines to retrieve. The default is all message lines. |
This is a high level method that encompasses the actions of many of the low level POP3 commands.
This method is suitable for applications with simple message processing requirements. More advanced applications should use the lower level POP3 commands for message processing.
Called with no parameters (or with both parameters as zero) RetrieveMessages () will populate all the elements of the Messages collection property with the messages from the maildrop and mark the messages for deletion from the server. This usage is designed to fulfill the requirements of a majority of simple applications.
Called with a non-zero Index parameter the object will retrieve the requested number of lines of the specified message from the maildrop and populate the corresponding element of the Messages collection property accordingly. If the number of lines requested is zero the entire message will be retrieved and the message will be marked for deletion from the server.
If partial messages are retrieved no attempt is made to decode the message or to split it into sections and the message is not marked for deletion from the server.
There is no return value from this method. If any error occurs while messages are being retrieved an error will be raised and should be handled through the VB/VBA/VBScript On Error mechanism.
While retrieving messages the object will:
· Issue a POP3 RETR command (if the entire message is to be retrieved) or TOP command (if a given number of lines are required) for each appropriate message.
· &nbs