UPOPMAIL

UPOPMAIL is an internal component that provides operations for sending and receiving email using SMTP and POP3 servers.

By calling the operations on the UPOPMAIL service, you can:

  • Connect and disconnect Uniface applications with SMTP and POP3 servers
  • Negotiate authentication to an email server using a security driver
  • Send email as plain text or HTML, or other supported MIME types
  • Include file attachments or inline objects in the mail message
  • List messages and download them from the POP3 server
  • Delete mail messages from the POP3 server

Unicode is supported for message subject and body, but not for user name and password or for the file names of attachments.

The UPOPMAIL component uses the Uniface network connectors to communicate with the POP3 and SMTP servers over TCP and TLS, and security drivers for authentication. For more information, see Communicating with Mail Servers, Security Context, and Security Drivers for Email Authentication.

Operations

Operation Purpose
Logon and authentication
LogonSMTP

LogoffSMTP

Logging on and off an SMTP server for sending mail
LogonMail

LogoffMail

Logging on and off a POP server for receiving mail
SetSecurity

GetSecurity

Using a security driver to handle authentication
Sending mail
SetToList

SetCCList

SetBCCList

SetReplyTo

SetFrom

SetSubject

SetPriority

SetMessageId

Defining the message header. The sender and at least once recipient are mandatory.
SetMessage

AddAttachmentFromFile

AddInlineFromFile

Defining the message content, including text, attachments, and inline objects
Send

SendMail

Sending the email as plain text or HTML.

Note:  The SendMail operation is available for backward compatibility, but it only supports plain text messages. The functionality it provides is now available using the other operations for sending email.

ClearMail

Clearing the memory allocated for sending the mail
Receiving mail
ListMail and ListMailX Listing the email messages on the POP3 server
GetMail and GetMailX

GetRawMail and GetRawMailX

Retrieving email messages from the POP3 server
DeleteMail Deleting mail on the POP3 server
Error handling
GetSMTPResponse

GetRecipientDetails

Getting GetRecipientDetailserror details when an error occurs.

Sending Email

The following example demonstrates how you to use some of the calls available on the UPOPMAIL component to send email in your application.

The LogonSMTP operation must always be called before the Send operation. The header must specify the sender and at least one recipient, so prior to using the Send operation, you must call the following operations:

  • LogonSMTP to connect with the SMTP server
  • SetFrom to specify the sender
  • SetToList, SetCCList, or SetBCCList to specify a recipient
;ProcScript module such as operation, entry, or Detail trigger
variables
    handle mailApiHandle
endvariables

; Create an instance handle of the UPOPMAIL API component
newinstance "UPOPMAIL", mailApiHandle

; Logon to the SMTP server
mailApiHandle->LogonSMTP("mailhost.mygreatcorp.net", "", "")

; Specify the mail header information
mailApiHandle->SetFrom(FROM.MESSAGE.DUMMY)
mailApiHandle->SetToList(TO.MESSAGE.DUMMY)
mailApiHandle->SetSubject(SUBJECT.MESSAGE.DUMMY)

; Specify the message body
mailApiHandle->SetMessage(TEXT, "")  ; plain text body
mailApiHandle->SetMessage(HTML, "MIMEType=text/html")  ; HTML body

; Add an attachment 
mailApiHandle->AddAttachmentFromFile(ATTACHMENT.MESSAGE.DUMMY, "")

; Send the message
mailApiHandle->Send("")

; Clear the mail message structure from memory
mailApiHandle->ClearMail()

; Log off the SMTP server
mailApiHandle->LogoffSMTP()

Retrieving Email

The following example shows how to retrieve the first email message for a specified user from the POP3 server.

First, a connection to the server is established with the LogonMail operation, then the number of mail messages (if any) is retrieved. Finally, the first message is retrieved. If there are no messages present, the call to GetMail is skipped. Any attachments are placed in c:\temp. 

variables
   handle  MailerHandle2-
   string  vEmailList, vEmailListPart
   numeric vTotalMails, vReceivedMail
 endvariables


; Logon to the POP server using the user id an password specified 
; in the component variables
MailerHandle2->LogonMail("pop3.mygreatcorp.net", $vUserID$, $vUserPassword$)

; Retrieve the email headers
MailerHandle2->ListMail(vEmailList)
if ($status = -16) ; -16 indicates that data exceeds 10K
    repeat
      MailerHandle2->ListMailX (vEmailListPart)
      if (vEmailList)
        ; Add the data to the existing email list 
         vEmailList = "%%vEmailList%%vEmailListPart" 
      else
         vEmailList = vEmailListPart
      endif
    until ($status != ""-16")
endif
vTotalMails = $status

; Retrieve the email messages 
if (vTotalMails > 0)
   vReceivedMail=1
   while (vReceivedMail < vTotalMails)
      creocc RECEIVED, 1
      MailerHandle2->GetMail(vReceivedMail, "c:\temp", 0 , HEADER.RECEIVED, MESSAGE.RECEIVED, ATTACHED.RECEIVED)
      if ($status = -16)
         repeat
            MailerHandle2->GetMailX(vReceivedMail, "c:\temp", 0 , HEADER.RECEIVED, MESSAGE.RECEIVED, ATTACHED.RECEIVED)
         until ($status != ""-16")
      endif
      vReceivedMail = vReceivedMail+1
   endwhile
endif

MailerHandle2->LogoffMail()

Error Handling

If you encounter the following $status return codes from the UPOPMAIL API, the connection has been closed and you need to log in again:

  • -4 Network time out
  • -8 Not logged on to the POP3 server
  • -9 Socket error

Related Topics