CreateMessage Method  

Begin the composition of a new message to be delivered.


object.CreateMessage( Sender, [MessageSize] )


A string which specifies the email address of the user sending the message. This typically corresponds to the address in the From header of the message, but it is not required that they be the same.
An integer which specifies the size of the message in bytes. If the size of the message is unknown, this argument should be omitted or passed as value of zero. This argument is ignored if the server does not support extended features. If the message size is larger than what the server will accept, this method will fail. Most Internet Service Providers impose a limit on the size of an email message, typically between 5 and 10 megabytes.

Return Value

A value of zero is returned if the method succeeds. Otherwise, a non-zero error code is returned which indicates the cause of the failure.


The CreateMessage method begins the composition of a new message to be submitted to the mail server for delivery. There are several steps that must be followed when dynamically composing a message using the CreateMessage method:

  1. Call the CreateMessage method to begin the message composition. The sender email address should generally be the same address as the one used in the "From" header field in the message.
  2. Call the AddRecipient method for each recipient of the message. These addresses are typically specified in the "To" and "Cc" header fields in the message. Additional addresses may also be be provided which are not specified in the email message itself. This is how one or more blind carbon copies of a message is delivered. Most servers have a limit on the total number of recipients that may be specified for a single message. This limit is usually around 100 addresses.
  3. Call the Write method to write the contents of the message to the data stream. The application may also choose to use the AppendMessage method to write out a large amount of message data.
  4. Call the CloseMessage method to close the message and submit it to the mail server for delivery.

For applications that do not need to dynamically compose the message and already have the message contents stored in a file or memory buffer, the SendMessage method is the preferred method of submitting a message for delivery.

See Also

AddRecipient Method, AppendMessage Method, CloseMessage Method, SendMessage Method, Write Method