Class MIMEMessage() Professional

Class function of the MIMEMessage class


Instances of the MIMEMessage class encapsulate the complexities of the Multipurpose Internet Mail Extensions, a specification for formatting non-ASCII messages so that they can be sent over the Internet. MIMEMessage objects are used to retrieve e-mail messages in conjunction with a POP3Client() object, or to send e-mails with a SMTPClient() object. This means that MIMEMessage objects are of no use on their own, but help a programmer to create and/or examine MIME e-mail messages in a comfortable way.

A MIMEMessage object takes care of all elements of an e-mail, that is, sender, recipients, headers, content and file attachments. Therefore, a MIMEMessage object plays a central role for sending/receiving e-mails with Xbase++ applications.

The MIMEMessage class does not feature specific interfaces for accessing every header field which may be used in an e-mail message. However, the methods:getHeader()and :addHeader() provide a generalized way for reading and writing arbitrary header values, and can be used in cases where no specific interface exists.

The following code snippet illustrates accessing the recipient of a message, the recipient of a carbon copy ("Cc"), and the recipient of a blind copy ("Bcc") of the same message:

oMimeMessage := MimeMessage():new() 

oMimeMessage:addRecipient( MailAddress():new( "" ) ) 
oMimeMessage:addHeader( "Cc", "" ) 
oMimeMessage:addHeader( "Bcc", "" ) 

? oMimeMessage:getHeader( "To" ) 
? oMimeMessage:getHeader( "Cc" ) 
? oMimeMessage:getHeader( "Bcc" ) 

The maintenance of different (mime) parts of an e-mail is the task of the subclass MIMEContent().

The class MailAddress() is used for stting the recipient with the method :addRecipient() and for determining the sender with the method :getFrom().

Class methods
Creates an instance of the MIMEMessage class.
Creates an instance of the MIMEMessage class from a string.
Methods for retrieving e-mails

Methods in this group are mainly used to examine the contents of an e-mail that is retrieved via oPOP3Client:getMessage(). This method returns a MIMEMessage object containing the different parts of an e-mail.

Retrieves the contents of all header fields.
Extracts the contents.
Retrieves the content transfer encoding.
Retrieves the content type.
Retrieves the creation date.
Retrieves the "From:" header.
Retrieves the contents of a header field.
Retrieves the "Subject:" line.
Methods for sending e-mails

Methods in this group are usually called when an e-mail message is assembled in an Xbase++ application. The mail is then sent to a mail server via a SMTPClient object and its :send() method.

Adds a header field.
Adds a "To:" header.
Attaches a file.
Deletes a header field.
Deletes a recipient.
Sets the contents of all header fields.
Defines the content transfer encoding.
Defines the content type.
Configures the sending of Delivery Service Notification e-mails
Defines the "From:" header.
Assigns the text body.
Defines the "Subject:" header.
Using a MIMEMessage object for sending an e-mail
// The example demonstrates how to assemble an e-mail 
// and send it via an SMTPCLient object to the recipient 

#include "" 

#define CRLF  Chr(13)+Chr(10) 

// Usage: <cEmailAdr>   Email address for both, the sender and recepient 
//        <cMailServer> Your mailserver ( "" ) 
//        <cUsername>   In case your mailserver requires authentification 
//                      the username can be passed 
//        <cPasswor>    Password for authentification 
PROCEDURE main( cEmailAdr, cMailServer, cUsername, cPassword ) 
   LOCAL oSmtp, oMail, oSender, cText, oRecipient 

   // This will be the message text 
   cText      := "Happy Birthday to Jane" + CRLF + CRLF 
   cText      += "Cheers" + CRLF 
   cText      += "  John" + CRLF 

   // create the MIMEMessage, the sender and the 
   // recipient object 
   oMail      := MIMEMessage():new() 
   oSender    := MailAddress():new( cEmailAdr ) 
   oRecipient := MailAddress():new( cEmailAdr ) 

   // Assemble the e-mail 
   // Set contact information 
   oMail:setFrom     ( oSender     ) 
   oMail:addRecipient( oRecipient  ) 
   oMail:addHeader   ( "Reply-To", cEmailAdr ) 

   // Set message contents 
   oMail:setSubject  ( "Greetings" ) 
   oMail:setMessage  ( cText       ) 

   // Connect to smtp server and send the mail 
   oSmtp := SMTPClient():new( cMailServer ) 
   IF oSmtp:connect( cUsername, cPassword ) 

      oSmtp:send( oMail ) 
      ? "Message sent" 
      ? "Unable to connect to mail server" 

Using a MIMEMessage object for sending an html e-mail
// The example demonstrates how to generate an e-mail from an html page. 
// Hereby the MimeMessage object is created by using class methods 
// from its baseclass MimeContent. Additionally a bitmap is added 
// to the mail as related content. 

#include "" 

// This sample demonstrates the creation of an html mail. 
// Usage: <cEmailAdr>   Email address for both, the sender and recepient 
//        <cMailServer> Your mailserver ( "" ) 
//        <cUsername>   In case your mailserver requires authentification 
//                      the username can be passed 
//        <cPasswor>    Password for authentification 
PROCEDURE main( cEmailAdr, cMailServer, cUsername, cPassword ) 
    LOCAL oMe, oMail, oServer, oBitmapCont 
    LOCAL cID 

    // For connecting to related content we need the same string 
    // in the html content as link and as header info in the 
    // related content 
    cID := MimeContent():new():uniqueString 

    // Parameter checking 
    IF PCount() < 2 
       ? "Usage:" 
       ? AppName(), "cEmailAdr cMailServer [cUsername] [cPassword]" 

    // One MAILAddress object for sender and recepient 
    oMe := MAILAddress():new( cEmailAdr ) 

    // Prepare MIMEMessage object. 
    // Create the MIMEMessage object QuotedPrintable encoded. 
    // EncodeQuotedPrintable is a class method of MIMEContent. 
    // The background image will be connected to the html page 
    // by parameter cID 
    oMail := MIMEMessage():encodeQuotedPrintable( getHtml(cEmailAdr, cID), ; 
                                                  "text/html" ) 

    oMail:setFrom( oMe ) 
    oMail:addRecipient( oMe ) 
    oMail:setSubject( "Asinet Html mail docu sample" ) 

    // Create the MIMEContent object containing the bitmap 
    oBitmapCont := getBitmapCont() 

    // Attach the Content that contains the bitmap 
    // Note that the same ID is required as in the html string. 
    // (see function getBitmapCont() below) 
    IF ! Empty( oBitmapCont ) 
       oMail:attachRelated( oBitmapCont, cID ) 

    // Create SMTPClient. Then connect to Server and send message. 
    oServer := SMTPClient():new( cMailServer ) 
    IF ! oServer:connect( cUsername, cPassword ) 
       ? "Unable to connect to mail server" 

    oServer:send( oMail ) 

    ? "Message sent!" 
    ? "Check account", cEmailAdr, "for new mail" 


// Helper method for creating a MimeContent object 
// from a bitmap 
FUNCTION getBitmapCont() 
   LOCAL cXppResource, oContent, nPos 

   // Extract bitmap resource path from environment 
   // variable 
   cXppResource := Lower( GetEnv( "XppResource" ) ) 
   IF 0 == ( nPos := At( "resource", cXppResource ) ) 
      ? "XppResource Environment variable not set:" 
      ? "  Background image can not be loaded" 
   // len( "resource" ) + 1 == 7 
   cXppResource := SubStr( cXppResource, 1, nPos + 7 ) 
   cXppResource += "\bitmap\keybd1.bmp" 

   // Create content from file 
   oContent := MimeContent():createFromFile( cXppResource ) 

RETURN oContent 

// Helper for returning a Html page 
FUNCTION getHtml( cMail, cID ) 
   LOCAL cStr := "" 
   cStr += '<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">' 
   // Here we use a link to the embedded picture 
   cStr += '<html>' 
   cStr += '  <head></head>' 
   cStr += '  <body background="cid:' + cID + '"' 
   cStr += '    <h1>' 
   cStr += '       Hallo from <br>'+cMail+'!' 
   cStr += '    <h1>' 
   cStr += '  </body>' 
   cStr += '</html>' 
Using a MIMEMessage object for retrieving an e-mail
// The example outlines the steps required for retrieving 
// an e-mail and examining its contents. The first mail 
// stored in a mailbox is retrieved, header fields are displayed 
// and file attachments are written to local files. 

#include "" 

   LOCAL nHandle, i, cText, aContent 
   LOCAL oPop3, oMail, oSender, oContent 

   LOCAL cFile     := NIL 
   LOCAL cServer   := "mail" 
   LOCAL cUserName := "JohnDoe" 
   LOCAL cPassword := "Lancelot" 

   oPop3 := POP3Client():new( cServer  , NIL      , ; 
                              cUserName, cPassWord  ) 

   IF .NOT. oPOP3:connect() 
      ? "Unable to establish connection to:", cServer 

   // receive the first message from the Pop server and 
   // extract the sender and an array with all MIMEContent 
   // objects 
   oMail    := oPOP3:getMessage(1) 
   oSender  := oMail:getFrom() 
   aContent := oMail:getContent() 

   ? "   From:", oSender:getString() 
   ? "Subject:", oMail:getSubject() 

   FOR i:=1 TO Len( aContent ) 
      oContent := aContent[i] 

      IF oContent:isMultiPart() 
         ? "Multi-part contents must be extracted recursively" 

      cText := oContent:getMessage() 

      DO CASE 
      CASE "text/" $ Lower( oContent:getContentType() ) 

         // This is printable content 
         ? "Content:", cText 

      CASE .NOT. Empty( cFile := oContent:getFileName() ) 

         // This is a file attachment 
         nHandle := FCreate( cFile ) 
         FWrite( nHandle, cText, Len( cText ) ) 
         FClose( nHandle ) 
         ? "Attachment written to:", cFile 


   // Remove the first message from the Pop server 


If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.