Index of E-Mail Components


1. Introduction

Zeus-Framework provides classes for E-Mailing. The E-Mail is devided into two groups: the transport protocol and the e-mail message format. Following classes are available in the current framework release:

  • TSMTProtocol: Transport protocol used to send an e-mail
  • TEMail: E-Mail message containing all information (content, recipients etc.)
  • TEMailAddress: Address of the sender or recipient

Sending e-mails often needs authentication. Two authentication methods are implemented and explained in this document:

  • LOGIN: standard login method sending a username and password directly to the server
  • NTLM: login method used to authenticate without sending password to server

The e-mailing components are included in the zeusbase/Net/Protocol package.


2. Simple Message Transfer Protocol SMTP

The simple message transfer protocol SMTP is an application protocol based on the TCP/IP protocol. SMTP is pure textual based. This chapter shows the basics of the SMTP. Some of the examples show how SMTP works, therefore we use telnet.

Additional and detailed information about SMTP you might find in following links:

2.1 Start the communication

To start the communication you need to create a simple TCP/IP socket. Normally the socket is connected with port 25 with the server. Following example shows the beginning of SMTP. You can directly input the data into telnet.


telnet smtp.bluewin.ch 25

S: 220 zhbdzmsp-nwas17.bluewin.ch ESMTP Service (Swisscom Schweiz AG) ready
C: HELO local.domain.com
S: 250 zhbdzmsp-nwas13 says HELO to 83.76.132.36:10373
C: QUIT
S: 221 zhbdzmsp-nwas17 closing connection

Typically a SMTP communication starts with the server (S) sending an OK for communication. Then the client (C) can send the HELO command. HELO needs an argument. You can give any name you want. The communication can be terminated with the QUIT command

If you use the Zeus-Framework you can directly create a TSMTProtocol object which automatically connects to the server and initializes the communication.


#include <zeusbase/Net/Protocols/SMTProtocol.h>

TAutoPtr<TSMTProtocol> ptrProtocol = new TSMTProtocol(L"smtp.bluewin.ch", 25);

//Its ready to send the e-mail

In contrast to the upper example the Zeus-Framework uses EHLO command. The server will list its known commands to the client. Zeus-Framework uses this replay to establish the correct authentication procedure.


telnet smtp.bluewin.ch 25

S: 220 zhbdzmsp-nwas17.bluewin.ch ESMTP Service (Swisscom Schweiz AG) ready
C: EHLO local.domain.com
S: 250-zhbdzmsp-nwas15 says EHLO to 83.76.132.36:10391
   250-PIPELINING
   250-8BITMIME
   250-SIZE 26214400
   250-AUTH=LOGIN
   250 AUTH LOGIN

2.2 Sending the mail

To send an E-Mail you have to tell first who you are. Lets look at the simplest way first, sending an e-mail without authentication. Even if this method is not safe it shows how SMTP works basically. With the command MAIL the e-mail transfer is started and with FROM: you can tell who you are.


telnet smtp.bluewin.ch 25

S: 220 zhbdzmsp-nwas17.bluewin.ch ESMTP Service (Swisscom Schweiz AG) ready
C: HELO local.domain.com
S: 250 zhbdzmsp-nwas13 says HELO to 83.76.132.36:10373
C: MAIL FROM: <This email address is being protected from spambots. You need JavaScript enabled to view it.>
S: 250 MAIL FROM accepted
C: RCPT TO: <This email address is being protected from spambots. You need JavaScript enabled to view it.>
S: 250 OK
C: RCPT TO: <This email address is being protected from spambots. You need JavaScript enabled to view it.>
S: 250 OK
C: DATA
S: 354 Start mail input; end with .
C: This is a test mail
   An other line of this mail

   .
S: 250 OK

To send a mail using the Zeus-Framework you simply create a TEMail object and pass it to the TSMTProtocol object.


#include <zeusbase/Net/Protocols/EMail.h>
#include <zeusbase/Net/Protocols/SMTProtocol.h>

TAutoPtr<TEMail> ptrMail = new TEMail(L"This email address is being protected from spambots. You need JavaScript enabled to view it.");
ptrMail->addRecipient(L"This email address is being protected from spambots. You need JavaScript enabled to view it.");
ptrMail->addRecipient(L"This email address is being protected from spambots. You need JavaScript enabled to view it.", TEMail::etCC);
ptrMail->setSubject(L"Test Mail");
ptrMail->setTextBody(L"This is a test mail");

TAutoPtr<TSMTProtocol> ptrProtocol = new TSMTProtocol(L"smtp.bluewin.ch", 25);
Retval retValue = ptrProtocol->sendEMail(*ptrMail);

2.3 Sending the mail with authentication

Nowadays there are many (or almost every) SMTP Server needing authentication. Many different methods exist. The current version of Zeus-Framework implements the two most used methods, LOGIN and NTLM. More information about login see Wikipedia SMTP-Auth.

2.3.1 Sending authenticated e-mail with Zeus-Framework

Sending a mail with authentication is easily done with the method sendAuthenticatedEMail(). The correct authentication method is automatically selected.


TAutoPtr<TSMTProtocol> ptrProtocol = new TSMTProtocol(L"smtp.bluewin.ch", 25);

ptrProtocol->sendAuthenticatedEMail(L"hans", L"schnitzelmitkartoffelsalat", *ptrMail);

2.3.2 Login

The LOGIN method is very simple. It sends the username and password directly to the server. The username and password are encoded with Base64. The following example uses the username "hans" and the password "schnitzelmitkartoffelsalat" (Wikipedia).


telnet smtp.bluewin.ch 25

S: 220 zhbdzmsp-nwas17.bluewin.ch ESMTP Service (Swisscom Schweiz AG) ready
C: HELO local.domain.com
S: 250 zhbdzmsp-nwas13 says HELO to 83.76.132.36:10373
C: AUTH LOGIN
S: 334 VXNlcm5hbWU6
C: aGFucw==
S: 334 UGFzc3dvcmQ6
C: c2Nobml0emVsbWl0a2FydG9mZmVsc2FsYXQ=
S: 235 Authed. Go on.
...sending the mail now

2.3.3 NTLM

The NTLM authentication is mostly used by Microsoft servers. Instead of sending the username and password to the server, this method first sends the username and gets a radnom number back from the server. The client sends encrypted random number back to the server. The random number is encrypted with the hash value of the users password. The server then compares the encrypted data with the internally encrypted data using the stored password. If both data sets are equal then the access is granted to the server.

A good description you find at http://davenport.sourceforge.net/ntlm.html.

In general the authentication is done with three messages.

  • Type 1 Message. This message is sent from client to the server and requests the authentication.
  • Type 2 Message. This message contains the challenge of the server.
  • Type 3 Message. The client must send the encrypted data back to the server with this type of message.

The Zeus-Framework provides a simple class to generate and parse the NTLM messages, TNTLMAuthentication. The code has been mainly taken from the NTLM authentication library 0.3.10.


#include <zeusbase/Security/NTLMAuthentication.h>
...
TNTLMAuthentication Authentication;

//generates the type 1 message
TString strRequest = Authentication.getRequestBase64();

if (sendToServer(strRequest))
{
  //read the type 2 message from server
  TString strChallenge = readfromServer();

  //Now generate the type 3 message
  TString strResponse = Authentication.getResponseBase64(strUserName, strPassword, strChallenge);

  if (sendToServer(strResponse))
  {
    //Authenticated to the server
  }
}


3. Links

Here are some more interesting links to SMTP:

Here are some more interesting links to authentication: