Loading...
Searching...
No Matches
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

| clearStats ()
| Clears performance statistics.
nothing | clearWarningQueue ()
| Removes any warning Queue object from the Socket.
| connect ()
| Connect to the server with the connection parameters set in the constructor()
| constructor (string host, softint port, *code log, *code dbglog)
| creates the SmtpClient object
| constructor (string url, *code log, *code dbglog)
| creates the SmtpClient object
| destructor ()
| disconnects if connected and destroys the object
| disconnect ()
| disconnect from the server
| forceDisconnect ()
| force disconnect of socket without error
date | getConnectTimeoutDate ()
| returns the connect timeout as a relative time value
int | getConnectTimeoutMs ()
| returns the connect timeout as an integer giving milliseconds
hash< auto > | getInfo ()
| Returns info about the connection.
date | getReadTimeoutDate ()
| returns the read timeout as a relative time value
int | getReadTimeoutMs ()
| returns the read timeout as an integer giving milliseconds
string | getTarget ()
| Returns the connection target string.
hash< auto > | getUsageInfo ()
| Returns performance statistics for the socket.
bool | isConnected ()
| return connection status
hash< auto > | sendMessage (MailMessage::Message message)
| send a Message to the server
| setConnectTimeout (timeout to)
| sets the connect timeout
| setDebugLogClosure (*code log)
| Set debug log closure.
| setEventQueue ()
| Removes any Queue object.
| setEventQueue (Qore::Thread::Queue queue, auto arg, *bool with_data)
| Sets a Queue object to receive socket events.
| setInfoLogClosure (*code log)
| Set info log closure.
| setReadTimeout (timeout to)
| sets the read timeout
| setUserPass (string n_user, string n_pass)
| sets the username and password for authenticated connections
nothing | setWarningQueue (int warning_ms, int warning_bs, Queue queue, auto arg, timeout min_ms=1s)
| Sets a Queue object to receive socket warnings.
bool | ssl ()
| returns the SSL connection flag
| ssl (bool n_ssl)
| sets the SSL connection flag
bool | test ()
| returns the test mode flag
| test (bool ns)
| sets or disables test mode; no connections are made in test mode
bool | tls ()
| returns the TLS/SSL flag
| tls (bool n_tls)
| sets 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

## 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

## clearStats()

SmtpClient::SmtpClient::clearStats | ( |  | ) |

Clears performance statistics.

Example:
  smtp.clearStats();

Since
  SmtpClient 1.3

See also
  getUsageInfo()

## clearWarningQueue()

nothing SmtpClient::SmtpClient::clearWarningQueue | ( |  | ) |

Removes any warning Queue object from the Socket.

Example:
  smtp.clearWarningQueue();

See also
  setWarningQueue()

Since
  SmtpClient 1.3

## connect()

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

## constructor() [1/2]

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

## constructor() [2/2]

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

creates the SmtpClient object

Example:
  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

## destructor()

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

## disconnect()

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

disconnect from the server

Note
  This method is subject to thread serialization

## forceDisconnect()

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

force disconnect of socket without error

Note
  This method is subject to thread serialization

## getInfo()

hash< auto > SmtpClient::SmtpClient::getInfo | ( |  | ) |

Returns info about the connection.

Returns
  info about the connection with the following keys:
  - `target:` the connection target (host:port)
  - `tls:` the tls flag
  - `ssl:` the ssl flag
  - `user:` any username for the connection
  - `pass:` any password for the connection

## getTarget()

string SmtpClient::SmtpClient::getTarget | ( |  | ) |

Returns the connection target string.

Since
  SmtpClient 1.7

## getUsageInfo()

hash< auto > SmtpClient::SmtpClient::getUsageInfo | ( |  | ) |

Returns performance statistics for the socket.

Example:
  hash<auto> h = smtp.getUsageInfo();

Returns
  a hash with the following keys:
  - `"bytes_sent"`: an integer giving the total amount of bytes sent
  - `"bytes_recv"`: an integer giving the total amount of bytes received
  - `"us_sent"`: an integer giving the total number of microseconds spent sending data
  - `"us_recv"`: an integer giving the total number of microseconds spent receiving data
  - `"arg"`: (only if warning values have been set with SmtpClient::setWarningQueue()) the optional argument for warning hashes
  - `"timeout"`: (only if warning values have been set with SmtpClient::setWarningQueue()) the warning timeout in microseconds
  - `"min_throughput"`: (only if warning values have been set with SmtpClient::setWarningQueue()) the minimum warning throughput in bytes/sec

Since
  SmtpClient 1.3

See also
  clearStats()

## sendMessage()

hash< auto > 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

## setEventQueue() [1/2]

SmtpClient::SmtpClient::setEventQueue | ( |  | ) |

Removes any Queue object.

After this call, socket events are no longer added to any currently-set Queue

Example:
  smtp.setEventQueue();

See also
  I/O Event Handling for more information

Since
  SmtpClient 1.8

## setEventQueue() [2/2]

SmtpClient::SmtpClient::setEventQueue | ( | Qore::Thread::Queue | queue,
|  | auto | arg,
|  | *bool | with_data
| ) |  |

Sets a Queue object to receive socket events.

Example:
  smtp.setEventQueue(queue);

Parameters

  queue | the Queue object to receive socket events; note that the Queue passed cannot have any maximum size set or a QUEUE-ERROR will be thrown
  arg | an argument that will be included in each event hash in the arg key
  with_data | if True, then the actual raw data transferred / received is also included in the events

Exceptions

  QUEUE-ERROR | the Queue passed has a maximum size set

See also
  I/O Event Handling for more information

Since
  SmtpClient 1.8

## setUserPass()

SmtpClient::SmtpClient::setUserPass | ( | string | n_user,
|  | string | n_pass
| ) |  |

sets the username and password for authenticated connections

Parameters

  n_user | the username to set for authentication
  n_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

## setWarningQueue()

nothing SmtpClient::SmtpClient::setWarningQueue | ( | int | warning_ms,
|  | int | warning_bs,
|  | Queue | queue,
|  | auto | arg,
|  | timeout | min_ms = `1s`
| ) |  |

Sets a Queue object to receive socket warnings.

Example:
  smtp.setWarningQueue(5000, 5000, queue, "socket-1");

Parameters

  warning_ms

  the threshold in milliseconds for individual socket actions (send, receive, connect), if exceeded, a socket warning is placed on the warning queue with the following keys:
  - `"type"`: a string with the constant value `"SOCKET-OPERATION-WARNING"`
  - `"operation"`: a string giving the operation that caused the warning (ex: `"connect"`)
  - `"us"`: an integer giving the number of microseconds for the operation
  - `"timeout"`: an integer giving the warning threshold in microseconds
  - `"arg"`: if any `"arg"` argument is passed to the SmtpClient::setWarningQueue() method, it will be included in the warning hash here

  warning_bs

  value in bytes per second; if any call has performance below this threshold, a socket warning is placed on the warning queue with the following keys:
  - `"type"`: a string with the constant value `"SOCKET-THROUGHPUT-WARNING"`
  - `"dir"`: either `"send"` or `"recv"` depending on the direction of the data flow
  - `"bytes"`: the amount of bytes sent
  - `"us"`: an integer giving the number of microseconds for the operation
  - `"bytes_sec"`: a float giving the transfer speed in bytes per second
  - `"threshold"`: an integer giving the warning threshold in bytes per second
  - `"arg"`: if any `"arg"` argument is passed to the SmtpClient::setWarningQueue() method, it will be included in the warning hash here

  queue | the Queue object to receive warning events
  arg | an optional argument to be placed in the `"arg"` key in each warning hash (could be used to identify the socket for example)
  min_ms | the minimum transfer time with a resolution of milliseconds for a transfer to be eligible for triggering a warning; transfers that take less than this period of time are not eligible for raising a warning

Exceptions

  QUEUE-ERROR | the Queue passed has a maximum size set
  SOCKET-SETWARNINGQUEUE-ERROR | at least one of warning_ms and warning_bs must be > 0

See also
  clearWarningQueue()

Since
  SmtpClient 1.3

## ssl()

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

sets the SSL connection flag

Parameters

  n_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

## tls()

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

sets the TLS/SSL flag

Parameters

  n_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

## Member Data Documentation

## SmtpsPort

const SmtpClient::SmtpClient::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