Emails with conzept 16 (Part 1)

conzept 16 offers the possibility to send e-mails directly from the application. There are many use cases for this: Be it a feedback function for the customer, a notification in the event of an error for the administrator or simply for sending files.

E-mails are sent using the mail functions. These use the Simple Mail Transfer Protocol (SMTP) for communication. The prerequisite is an accessible and SMTP-capable mail server.

In a previous article, we already presented a method for receiving emails with conzept 16.

Overview of the functions for sending:

• MailOpen() – Create e-mail
• MailData() – Compose e-mail
  • Define message header
  • Define message content
  • Add attachments
• MailClose() – Send e-mail

Create e-mail

Command MailOpen() is used to create an e-mail. This function saves the connection data to the mail server and reserves a memory area for storing the message.

The type of Kommunikation zum Mailserver is defined in the first parameter. The name or IP address of the mail server is specified in the second parameter.

The function returns the descriptor for a mail object.

// Establish an unencrypted connection to the mail server
tMail # MailOpen(_MailSMTP, sMyMailserver);

// VEstablish an encrypted connection to the mail server via SSL/TLS
tMail # MailOpen(_MailSMTPS, sMyMailserver);

The default port for SMTP is port 25. If the mail server expects communication on a different port, this can be defined in the third parameter. Furthermore, a timeout and login data, consisting of user name and password, can be specified for the mail server when creating the email.

// Connection via port 50001
tMail # MailOpen(_MailSMTP, sMyMailserver, 50001);

// Connection with 30 second timeout and authentication
tMail # MailOpen(_MailSMTP, sMyMailserver, 0, 30, sMyUser, sMyPwd);

No connection to the mail server is established at this point. An invalid mail server address or incorrect login details are only recognized when the email is sent.

Define header

The header of an email consists of several entries. Each entry represents a property of the email, e.g. sender, recipient or creation date. These entries can be defined using function MailData(). The function expects the descriptor of a mail object as the first parameter. In the second parameter, a constant is used to specify which header entry should be created. An overview of the constants can be found in the conzept 16 documentation under the index entry “MailData – Message header”. The value of the header entry is defined in the third parameter. An addition to the entry can be specified in the fourth parameter, for example the display name for an address.

// Define sender
tMail->MailData(_SMTPFrom, '', 'Emil A. D. Resse');

// Add recipient
tMail->MailData(_SMTPTo, '', 'vectorsoft AG (Support)');

// Define subject
tMail->MailData(_SMTPSubject, 'Frage zu CONZEPT 16');

Every e-mail must have a sender and at least one recipient!

Several recipients, CCs and BCCs can be defined. To do this, the respective instruction is called several times.

DSN (Delivery Status Notification)-Kommandos can be defined in the fourth parameter.

The function returns an error value.

Define message content

The message content, i.e. the actual text in the email, is also defined using the MailData() command. A plain text and an HTML text (_MimeTextHTML) can be defined for each email. The HTML text is optional and should always be defined after the plain text, otherwise an email client may not be able to display the email correctly.

A plain text should always be sent so that all e-mail clients that are not HTML-capable can display the e-mail.

There are generally three ways to define the message content:

• From a text buffer (_MailBuffer),
• from an external file (_MailFile) oder
• line-by-line (_MailLine).

If the message content comes from a text buffer, its descriptor must be converted into an alpha value.

Example of a text buffer:

// Plain
tMail->MailData(_MailBuffer, CnvAI(tTextASCII, _FmtInternal));

// HTML
tMail->MailData(_MailBuffer | _MimeTextHTML, CnvAI(tTextHTML, _FmtInternal));

Example for external files:

// Plain
tMail->MailData(_MailFile, _Sys->spPathMyDocuments + 'mail.txt');

// HTML
tMail->MailData(_MailFile | _MimeTextHTML, _Sys->spPathMyDocuments + 'mail.html');

Example of line-by-line definition:

// Plain
tMail->MailData(_MailLine, 'Dear Sir or Madam,');
tMail->MailData(_MailLine, ''); // Space
...
tMail->MailData(_MailLine, 'With kind regards');
...

// HTML
tMail->MailData(_MailLine | _MimeTextHTML, '<html><body>');
tMail->MailData(_MailLine | _MimeTextHTML, '<p>Dear Sir or Madam,</p>');
...
tMail->MailData(_MailLine | _MimeTextHTML, '<p>With kind regards</p>');
...
tMail->MailData(_MailLine | _MimeTextHTML, '</body></html>');

Add attachments

If an additional MIME type (Multipurpose Internet Mail Extension) is specified for command MailData(), an external file can be added as an attachment to the email. The MIME type specifies the type of data to be transferred.

The file name in the email is taken from the external file.

// Add image
tMail->MailData(_MailFile | _MimeImageJPEG, _Sys->spPathMyPictures + 'image.jpg');

// Add ZIP file
tMail->MailData(_MailFile | _MimeAppZIP, _Sys->spPathMyDocuments + 'info.zip');

Send e-mail

Sending the email is enabled via command MailClose(). The argument _SMTPSendNow is passed to the function. If the created e-mail is supposed to be discarded, _SMTPDiscard must be specified as an argument.

The function returns an error value as the result.

// Send e-mail
tMail->MailClose(_SMTPSendNow);

// Discard e-mail
tMail->MailClose(_SMTPDiscard);

Outlook

There will be an additional article on the mail functions. This will explain the topics of encoding, character set, using special MIME types and embedding resources – e.g. images – in HTML emails.