Qore SmtpClient Module Reference 1.2

- Main Page
- Namespaces
- Classes

- Class List
- Class Index
- Class Hierarchy
- Class Members

All Classes Namespaces Functions Variables Groups Pages
Public Member Functions | Public Attributes | List of all members
SmtpClient::SmtpClient Class Reference

the class that's used to communicate with an SMTP server and supports optional TLS/SSL encryption More...

## Public Member Functions
| connect ()
| Connect to the server with the connection parameters set in the constructor() More...
| constructor (string host, softint port, *code log, *code dbglog)
| creates the SmtpClient object More...
| constructor (string url, *code log, *code dbglog)
| creates the SmtpClient object More...
| destructor ()
| disconnects if connected and destroys the object More...
| disconnect ()
| disconnect from the server More...
| forceDisconnect ()
| force disconnect of socket without error More...
date | getConnectTimeoutDate ()
| returns the connect timeout as a relative time value
int | getConnectTimeoutMs ()
| returns the connect timeout as an integer giving milliseconds
date | getReadTimeoutDate ()
| returns the read timeout as a relative time value
int | getReadTimeoutMs ()
| returns the read timeout as an integer giving milliseconds
bool | isConnected ()
| return connection status
hash | sendMessage (MailMessage::Message message)
| send a Message to the server More...
| setConnectTimeout (timeout to)
| sets the connect timeout
| setReadTimeout (timeout to)
| sets the read timeout
| setUserPass (string user, string pass)
| sets the username and password for authenticated connections More...
| ssl (bool ssl)
| sets the SSL connection flag More...
bool | ssl ()
| returns the SSL connection flag
| test (bool ns)
| sets or disables test mode; no connections are made in test mode
bool | test ()
| returns the test mode flag
| tls (bool tls)
| sets the TLS/SSL flag More...
bool | tls ()
| returns the TLS/SSL flag

## Public Attributes
const | EsmtpPort = 587
| default ESMTP port
const | Protocols
| procotol config
const | SmtpPort = 25
| default SMTP port
const | SmtpsPort = 465
| default SMTPS port; note that this port 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

## Detailed Description

the class that's used to communicate with an SMTP server and supports optional TLS/SSL encryption

This class uses a Mutex lock in each SmtpClient object to ensure thread serialization to the underlying socket and its internal configuration, so it is safe to access in a multithreaded context.

## Member Function Documentation

SmtpClient::SmtpClient::connect | ( |  | ) |

Connect to the server with the connection parameters set in the constructor()

Note
  - For possible exceptions, see Qore's Socket::connect() method
  - This method is subject to thread serialization

SmtpClient::SmtpClient::constructor | ( | string | host,
|  | softint | port,
|  | *code | log,
|  | *code | dbglog
| ) |  |

creates the SmtpClient object

Parameters

  host | the hostname of the SMTP server (use `"[hostname]"` to explicitly specify an ipv6 connection)
  port | the port number of the SMTP server
  log | a closure or call reference for log messages; a single string argument will be passed to this code for logging
  dbglog | a closure for debugging/technical log messages; a single string argument will be passed to this code for logging

SmtpClient::SmtpClient::constructor | ( | string | url,
|  | *code | log,
|  | *code | dbglog
| ) |  |

creates the SmtpClient object

Example:
  my SmtpClient $smtp("smtptls://user@gmail.com:password@smtp.gmail.com", \log(), \log());

Parameters

  url | the URL of the SMTP server (use `"[hostname]"` or `"[address]"` for ipv6 connections); if no protocol (scheme) and no port is given for non-UNIX sockets, then SmtpPort is used as the default port number. This argument is parsed with parse_url(); see smtpclient_protocols for a description of the handling of the protocol (scheme) component of the URL including default ports per protocol (scheme). If an unknown protocol (scheme) is given then a `SMTP-UNKNOWN-PROTOCOL` exception is raised
  log | an optional closure or call reference for log messages; a single string argument will be passed to this code for logging
  dbglog | an optional closure or call reference for debugging/technical log messages; a single string argument will be passed to this code for logging

Exceptions

  PARSE-URL-ERROR | the url argument could not be parsed with parse_url()
  SMTPCLIENT-UNKNOWN-PROTOCOL | the protocol (scheme) given is unknown or unsupported
  SMTPCLIENT-INVALID-AUTHENTICATION | partial authentication credentials passed; the username or password is missing

SmtpClient::SmtpClient::destructor | ( |  | ) |

disconnects if connected and destroys the object

if any exceptions occur during the disconnection, they are sent to the debug log closure/call reference

SmtpClient::SmtpClient::disconnect | ( |  | ) |

disconnect from the server

Note
  This method is subject to thread serialization

SmtpClient::SmtpClient::forceDisconnect | ( |  | ) |

force disconnect of socket without error

Note
  This method is subject to thread serialization

hash SmtpClient::SmtpClient::sendMessage | ( | MailMessage::Message | message | ) |

send a Message to the server

Parameters

  message | the Message to send

Returns
  a hash of data returned by the SMTP server (the return structure hashes described below are made up of the following keys: `"code"`: the return code, `"desc"`: the string description):
  - `HELO` or `EHLO:` a hash of the reply received from the `HELO` or `EHLO` command
  - `RCPT:` hash keyed by email address with hash return structures values for the RCPT TO command
  - `MSGID:` return structure after the send; generally contains message id
  - `QUIT:` the server response of the disconnect command

Note
  This method is subject to thread serialization

Exceptions

  MESSAGE-ERROR | the message is incomplete and cannot be sent

SmtpClient::SmtpClient::setUserPass | ( | string | user,
|  | string | pass
| ) |  |

sets the username and password for authenticated connections

Parameters

  user | the username to set for authentication
  pass | the password to set for authentication

Note
  - Currently this class only knows how to do AUTH PLAIN authentication
  - This method is subject to thread serialization

SmtpClient::SmtpClient::ssl | ( | bool | ssl | ) |

sets the SSL connection flag

Parameters

  ssl | if True then connections to the SMTP server will immediately try to negotiate transport layer TSL/SSL security; will also in this case turn off the TLS/SSL `"STARTTLS"` application layer security flag

SmtpClient::SmtpClient::tls | ( | bool | tls | ) |

sets the TLS/SSL flag

Parameters

  tls | if True then use TLS/SSL; if the TLS/SSL flag is set then the client will issue a `"STARTTLS"` command after connecting and negotiate a secure TLS/SSL connection to the server; will also in this case turn off the SSL connection flag