TSmtp

Source: source/classes/tsmtp.prg

TSmtp is FiveWin's email-sending class. It implements the SMTP protocol to send messages through a mail server, with support for authentication (AUTH LOGIN), HTML content, file attachments, CC/BCC recipients, and return receipts. It is built on top of TSocket and uses the asynchronous event model for communication.

Key DATA Members

DATA	Type	Default	Description
`cIPServer`	Character		SMTP server hostname or IP address
`nPort`	Numeric	`25`	SMTP server port
`cFrom`	Character		Sender email address
`aTo`	Array	`{}`	Array of recipient email addresses
`aCC`	Array	`{}`	Array of CC recipient addresses
`aBCC`	Array	`{}`	Array of BCC recipient addresses
`cSubject`	Character	`"[no subject]"`	Email subject line
`cMsg`	Character	`""`	Plain text message body
`cHTML`	Character	`""`	HTML message body (alternative to plain text)
`aFiles`	Array	`{}`	Array of file paths to attach
`cPriority`	Character	`"Normal"`	Message priority: Normal, High, or Low
`cUser`	Character	`""`	Username for SMTP authentication
`cPassword`	Character	`""`	Password for SMTP authentication
`lDoAuth`	Logical	`.F.`	Enable SMTP authentication (AUTH LOGIN)
`cReplyTo`	Character		Reply-To email address
`lReceipt`	Logical	`.F.`	Request a return receipt (Disposition-Notification-To)
`cMailer`	Character	`"FiveWin Mailer"`	X-Mailer header value
`cError`	Character	`""`	Error description if sending fails
`bConnecting`	Block		Callback during connection
`bConnected`	Block		Callback when connected to server
`bDone`	Block		Callback when message is successfully sent
`bFailure`	Block		Callback when an error occurs

Methods

Method	Description
`New( cIPServer, nPort, lAuth, cUser, cPassword )`	Create a new SMTP session. nPort defaults to 25. Resolves hostname to IP if needed.
`SendMail( cFrom, aTo, cMsg, cSubject, aFiles, aCC, aBCC, lReceipt, cHTML )`	Compose and send an email. All parameters after aTo are optional.
`End()`	Close the underlying socket and clean up
`Priority()`	Return numeric priority: 1=High, 3=Normal, 5=Low

Example: Send a Simple Email

#include "FiveWin.ch"

function Main()

   local oSmtp

   oSmtp := TSmtp():New( "mail.example.com" )

   oSmtp:SendMail( "sender@example.com", ;
                   { "recipient@example.com" }, ;
                   "Hello, this is a test message.", ;
                   "Test Subject" )

return nil

Example: Authenticated SMTP with Attachment

#include "FiveWin.ch"

function Main()

   local oSmtp

   // Gmail SMTP with authentication
   oSmtp := TSmtp():New( "smtp.gmail.com", 587, .T., ;
                         "user@gmail.com", "password" )

   oSmtp:bConnecting := { || MsgInfo( "Connecting to SMTP server..." ) }
   oSmtp:bDone       := { || MsgInfo( "Email sent successfully!" ) }
   oSmtp:bFailure    := { |o,n,c| MsgStop( "Error: " + oSmtp:cError ) }

   oSmtp:SendMail( "user@gmail.com", ;
                   { "recipient@example.com" }, ;
                   "Please find the attached report.", ;
                   "Monthly Report", ;
                   { "C:\reports\report.pdf" } )

return nil

Example: HTML Email with CC

#include "FiveWin.ch"

function Main()

   local oSmtp, cHtml

   TEXT INTO cHtml
   <html>
   <body style="font-family: Arial; color: #333;">
      <h1>Welcome!</h1>
      <p>This is an <b>HTML email</b> sent from FiveWin.</p>
      <hr>
      <p>Regards,<br>The FiveWin Team</p>
   </body>
   </html>
   ENDTEXT

   oSmtp := TSmtp():New( "mail.example.com" )

   oSmtp:SendMail( "sender@example.com", ;
                   { "alice@example.com" }, ;
                   "Plain text fallback message.", ;
                   "HTML Email Test", , ;
                   { "bob@example.com" }, ;   // CC
                   .F., cHtml )

return nil

Notes

TSmtp supports the AUTH LOGIN authentication method. For servers requiring PLAIN or MD5, additional implementation is needed.
The server hostname (cIPServer) can be a friendly name (e.g. "smtp.gmail.com") or an IP address. TSmtp resolves it automatically.
Attachments are encoded as base64 for binary files or quoted-printable for text files. File names preserve their original case.
HTML emails include a multipart/alternative structure: a plain text fallback is sent alongside the HTML content.
If the server times out after sending large attachments, increment the nDelay DATA member by one to add delay between sends.