Qore SmtpClient Module Reference  1.7
SmtpClient Module

SmtpClient Introduction

The SmtpClient module provides a set of classes that can be used for easy communication with SMTP servers for sending emails, with or without TLS/SSL encryption.

To use this module, use "%requires SmtpClient" in your code. See examples/email.q for an example program using this module

All the public symbols in the module are defined in the SmtpClient namespace

Classes provided:

The following supporting classes are provided by the MailMessage module:

Note that the SmtpClient class automatically detects if the SMTP server supports ESMTP and a "EHLO" command is executed automatically instead of "HELO" if so. Additionally, the class also automatically detects if the server supports the "STARTTLS" command by parsing the response to the "EHLO" command when talking to ESMTP servers.

If the tls flag is not set on the SmtpClient object and the server supports "STARTTLS" (and a transport layer TLS/SSL connection was not already established), then the SmtpClient object will automatically execute a "STARTTLS" command after connecting so that the rest of the SMTP session is performed securely. This also allows transparent logins and communication with ESMTP servers that require secure connections.

For the above reasons it's normally not required to use the "smtptls" or "esmtptls" protocols in the SmtpClient::constructor(string, *code, *code) URL argument.

The SmtpClient::constructor(string, *code, *code) takes a URL argument, the protocol (scheme) component is handled as in the following table.

SmtpcClient Protocol Handling

Protocol Default Port Description
"smtp" 25 standard SMTP port without encryption; ESMPT and "STARTTLS" detection is supported automatically
"smtps" 465 note that port 465 is currently assigned to source-specific multicast audio/video (http://www.iana.org/assignments/port-numbers); it's use as a port for secure SMTP listeners (where security is enforced at the transport layer because the server immediately negotiates a TLS/SSL connection before the application protocol communication starts) is deprecated but is included in this module because many SMTP servers still operate this way
"smtptls" 25 a "STARTTLS" command is executed unconditionally after the connection to ensure a secure connection, even if the server does not declare support for this command in the login response. It's normally not necessary to use this protocol as "STARTTLS" is used automatically when logging in to ESMTP servers that declare support for this command in the response to the "EHLO" command.
"esmtp" 587 like "smtp" just using port 587
"esmtptls" 587 like "smtptls" just using port 587
Example:
%requires SmtpClient
%requires Mime
Message msg("The Sender <sender@email.com>", "My Subject");
msg.setBody(body);
msg.addTO("My Best Friend <you@friend.com>");
msg.attach(filename, Mime::MimeTypeText, data);
code log = sub (string str) {printf("%y: %s\n", now_us(), str);};
SmtpClient::SmtpClient smtp("esmtptls://user@password:smtp.example.com", log, log);
smtp.sendMessage(msg);

SmtpClient References

Based on:

SmtpClient Release Notes

SmtpClient 1.7

SmtpClient 1.6

SmtpClient 1.5

SmtpClient 1.4

  • fixed missing username and missing password errors

SmtpClient 1.3

  • added socket instrumention support from Qore 0.8.9
  • optimized connection and login code; HELO/EHLO and authorization are performed when connecting only; not before each email

SmtpClient 1.2

  • added support for parsing a full URL in the SmtpClient::constructor(); added protocol support and setting the username / password from the URL
  • use Message::checkSendPossible() to throw a more descriptive exception if the message is incomplete and not ready to be sent
  • implemented support for automatically detecting if the server accepts the STARTTLS command and, if so, automatically setting the STARTTLS flag if it's not already set

SmtpClient 1.1

  • removed the Message and Attachment classes to the MailMessage module to be reused in the Pop3Client module

SmtpClient 1.0

+ updated to a user module, added initial rudimentary ESMTP handling, STARTTLS and quoted-printable encoding support + documentation