LimeSurvey API - Master branch
Back to top  

SMTP

PHPMailer RFC821 SMTP email transport class.

Implements RFC 821 SMTP commands and provides some utility methods for sending mail to an SMTP server.

author

Chris Ryan
author

Marcus Bointon phpmailer@synchromedia.co.uk
package

Default

Methods

Perform SMTP authentication.

authenticate(string $username,string $password,string $authtype = null,\PHPMailer\PHPMailer\OAuthTokenProvider $OAuth = null): boolean

Must be run after hello().

see \PHPMailer\PHPMailer\SMTP::hello()

Arguments

$username

string

The user name

$password

string

The password

$authtype

string

The auth type (CRAM-MD5, PLAIN, LOGIN, XOAUTH2)

$OAuth

\PHPMailer\PHPMailer\OAuthTokenProvider

An optional OAuthTokenProvider instance for XOAUTH2 authentication

Response

boolean

True if successfully authenticated

Send raw data to the server.

client_send(string $data,string $command = ''): integer|boolean

Arguments

$data

string

The data to send

$command

string

Optionally, the command this is part of, used only for controlling debug output

Response

integer|boolean

The number of bytes sent to the server or false on error

Close the socket and clean up the state of the class.

close()

Don't use this function without first trying to use QUIT.

see \PHPMailer\PHPMailer\SMTP::quit()

Connect to an SMTP server.

connect(string $host,integer $port = null,integer $timeout = 30,array $options = array()): boolean

Arguments

$host

string

SMTP server IP or host name

$port

integer

The port number to connect to

$timeout

integer

How long to wait for the connection to open

$options

array

An array of options for stream_context_create()

Response

boolean

Check connection state.

connected(): boolean

Response

boolean

True if connected

Send an SMTP DATA command.

data(string $msg_data): boolean

Issues a data command and sends the msg_data to the server, finalizing the mail transaction. $msg_data is the message that is to be send with the headers. Each header needs to be on a single line followed by a with the message headers and the message body being separated by an additional . Implements RFC 821: DATA .

Arguments

$msg_data

string

Message data to send

Response

boolean

Output debugging info via a user-selected method.

edebug(string $str,integer $level)
see \PHPMailer\PHPMailer\SMTP::Debugoutput\PHPMailer\PHPMailer\SMTP::do_debug

Arguments

$str

string

Debug string to output

$level

integer

The debug level of this message; see DEBUG_* constants

Reports an error number and string.

errorHandler(integer $errno,string $errmsg,string $errfile = '',integer $errline)

Arguments

$errno

integer

The error number returned by PHP

$errmsg

string

The error message returned by PHP

$errfile

string

The file the error occurred in

$errline

integer

The line number the error occurred on

Read the SMTP server's response.

get_lines(): string

Either before eof or socket timeout occurs on the operation. With SMTP we can tell if we have more lines to read if the 4th character is '-' symbol. If it is a space then we don't need to read anything else.

Response

string

Get debug output level.

getDebugLevel(): integer

Response

integer

Get debug output method.

getDebugOutput(): string

Response

string

Get the latest error.

getError(): array

Response

array

Get the last reply from the server.

getLastReply(): string

Response

string

Get the queue/transaction ID of the last SMTP transaction If no reply has been received yet, it will return null.

getLastTransactionID(): boolean|string|null

If no pattern was matched, it will return false.

see \PHPMailer\PHPMailer\SMTP::recordLastTransactionID()

Response

boolean|string|null

Get metadata about the SMTP server from its HELO/EHLO response.

getServerExt(string $name): string|boolean|null

The method works in three ways, dependent on argument value and current state:

  1. HELO/EHLO has not been sent - returns null and populates $this->error.
  2. HELO has been sent - $name == 'HELO': returns server name $name == 'EHLO': returns boolean false $name == any other string: returns null and populates $this->error
  3. EHLO has been sent - $name == 'HELO'|'EHLO': returns the server name $name == any other string: if extension $name exists, returns True or its options (e.g. AUTH mechanisms supported). Otherwise returns False.

Arguments

$name

string

Name of SMTP extension or 'HELO'|'EHLO'

Response

string|boolean|null

Get SMTP extensions available on the server.

getServerExtList(): array|null

Response

array|null

Create connection to the SMTP server.

getSMTPConnection(string $host,integer $port = null,integer $timeout = 30,array $options = array()): false|resource

Arguments

$host

string

SMTP server IP or host name

$port

integer

The port number to connect to

$timeout

integer

How long to wait for the connection to open

$options

array

An array of options for stream_context_create()

Response

false|resource

Get SMTP timeout.

getTimeout(): integer

Response

integer

Get VERP address generation mode.

getVerp(): boolean

Response

boolean

Send an SMTP HELO or EHLO command.

hello(string $host = ''): boolean

Used to identify the sending server to the receiving server. This makes sure that client and server are in a known state. Implements RFC 821: HELO and RFC 2821 EHLO.

Arguments

$host

string

The host name or IP to connect to

Response

boolean

Calculate an MD5 HMAC hash.

hmac(string $data,string $key): string

Works like hash_hmac('md5', $data, $key) in case that function is not available.

Arguments

$data

string

The data to hash

$key

string

The key to hash with

Response

string

Send an SMTP MAIL command.

mail(string $from): boolean

Starts a mail transaction from the email address specified in $from. Returns true if successful or false otherwise. If True the mail transaction is started and then one or more recipient commands may be called followed by a data command. Implements RFC 821: MAIL FROM: .

Arguments

$from

string

Source address of this message

Response

boolean

Send an SMTP NOOP command.

noop(): boolean

Used to keep keep-alives alive, doesn't actually do anything.

Response

boolean

Parse a reply to HELO/EHLO command to discover server extensions.

parseHelloFields(string $type)

In case of HELO, the only parameter that can be discovered is a server name.

Arguments

$type

string

HELO or EHLO

Send an SMTP QUIT command.

quit(boolean $close_on_error = true): boolean

Closes the socket if there is no error or the $close_on_error argument is true. Implements from RFC 821: QUIT .

Arguments

$close_on_error

boolean

Should the connection close if an error occurs?

Response

boolean

Send an SMTP RCPT command.

recipient(string $address,string $dsn = ''): boolean

Sets the TO argument to $toaddr. Returns true if the recipient was accepted false if it was rejected. Implements from RFC 821: RCPT TO: .

Arguments

$address

string

The address the message is being sent to

$dsn

string

Comma separated list of DSN notifications. NEVER, SUCCESS, FAILURE or DELAY. If you specify NEVER all other notifications are ignored.

Response

boolean

Extract and return the ID of the last SMTP transaction based on a list of patterns provided in SMTP::$smtp_transaction_id_patterns.

recordLastTransactionID(): boolean|string|null

Relies on the host providing the ID in response to a DATA command. If no reply has been received yet, it will return null. If no pattern was matched, it will return false.

Response

boolean|string|null

Send an SMTP RSET command.

reset(): boolean

Abort any transaction that is currently in progress. Implements RFC 821: RSET .

Response

boolean

True on success

Send an SMTP SAML command.

sendAndMail(string $from): boolean

Starts a mail transaction from the email address specified in $from. Returns true if successful or false otherwise. If True the mail transaction is started and then one or more recipient commands may be called followed by a data command. This command will send the message to the users terminal if they are logged in and send them an email. Implements RFC 821: SAML FROM: .

Arguments

$from

string

The address the message is from

Response

boolean

Send a command to an SMTP server and check its return code.

sendCommand(string $command,string $commandstring,integer|array $expect): boolean

Arguments

$command

string

The command name - not sent to the server

$commandstring

string

The actual command to send

$expect

integer|array

One or more expected integer success codes

Response

boolean

True on success

Send an SMTP HELO or EHLO command.

sendHello(string $hello,string $host): boolean

Low-level implementation used by hello().

see \PHPMailer\PHPMailer\SMTP::hello()

Arguments

$hello

string

The HELO string

$host

string

The hostname to say we are

Response

boolean

Set debug output level.

setDebugLevel(integer $level)

Arguments

$level

integer

Set debug output method.

setDebugOutput(string|callable $method = 'echo')

Arguments

$method

string|callable

The name of the mechanism to use for debugging output, or a callable to handle it

Set error messages and codes.

setError(string $message,string $detail = '',string $smtp_code = '',string $smtp_code_ex = '')

Arguments

$message

string

The error message

$detail

string

Further detail on the error

$smtp_code

string

An associated SMTP error code

$smtp_code_ex

string

Extended SMTP code

Set SMTP timeout.

setTimeout(integer $timeout)

Arguments

$timeout

integer

The timeout duration in seconds

Enable or disable VERP address generation.

setVerp(boolean $enabled = false)

Arguments

$enabled

boolean

Initiate a TLS (encrypted) session.

startTLS(): boolean

Response

boolean

Send an SMTP TURN command.

turn(): boolean

This is an optional command for SMTP that this class does not support. This method is here to make the RFC821 Definition complete for this class and may be implemented in future. Implements from RFC 821: TURN .

Response

boolean

Send an SMTP VRFY command.

verify(string $name): boolean

Arguments

$name

string

The name to verify

Response

boolean

Constants

The PHPMailer SMTP version number.

VERSION
var

SMTP line break constant.

LE
var

The SMTP port to use if one is not specified.

DEFAULT_PORT
var

The maximum line length allowed by RFC 5321 section 4.5.3.1.6, *excluding* a trailing CRLF break.

MAX_LINE_LENGTH
see
var

The maximum line length allowed for replies in RFC 5321 section 4.5.3.1.5, *including* a trailing CRLF line break.

MAX_REPLY_LENGTH
see
var

Debug level for no output.

DEBUG_OFF
var

Debug level to show client -> server messages.

DEBUG_CLIENT
var

Debug level to show client -> server and server -> client messages.

DEBUG_SERVER
var

Debug level to show connection status, client -> server and server -> client messages.

DEBUG_CONNECTION
var

Debug level to show all messages.

DEBUG_LOWLEVEL
var

Properties

Debug output level.

do_debug :integer

Options:

  • self::DEBUG_OFF (0) No debug output, default
  • self::DEBUG_CLIENT (1) Client commands
  • self::DEBUG_SERVER (2) Client commands and server responses
  • self::DEBUG_CONNECTION (3) As DEBUG_SERVER plus connection status
  • self::DEBUG_LOWLEVEL (4) Low-level data output, all messages.
var

Type(s)

integer

How to handle debug output.

Debugoutput :string|callable|\Psr\Log\LoggerInterface

Options:

  • echo Output plain-text as-is, appropriate for CLI
  • html Output escaped, line breaks converted to <br>, appropriate for browser output
  • error_log Output to error log as configured in php.ini Alternatively, you can provide a callable expecting two params: a message string and the debug level:
$smtp->Debugoutput = function($str, $level) {echo "debug level $level; message: $str";};

Alternatively, you can pass in an instance of a PSR-3 compatible logger, though only debug level output is used:

$mail->Debugoutput = new myPsr3Logger;
var

Type(s)

string|callable|\Psr\Log\LoggerInterface

Whether to use VERP.

do_verp :boolean
see

Info on VERP
var

Type(s)

boolean

The timeout value for connection, in seconds.

Timeout :integer

Default of 5 minutes (300sec) is from RFC2821 section 4.5.3.2. This needs to be quite high to function correctly with hosts using greetdelay as an anti-spam measure.

see
var

Type(s)

integer

How long to wait for commands to complete, in seconds.

Timelimit :integer

Default of 5 minutes (300sec) is from RFC2821 section 4.5.3.2.

var

Type(s)

integer

Patterns to extract an SMTP transaction id from reply to a DATA command.

smtp_transaction_id_patterns :array<mixed,string>

The first capture group in each regex will be used as the ID. MS ESMTP returns the message ID, which may not be correct for internal tracking.

var

Type(s)

array<mixed,string>

The last transaction ID issued in response to a DATA command, if one was detected.

last_smtp_transaction_id :string|boolean|null
var

Type(s)

string|boolean|null

The socket for the server connection.

smtp_conn :\PHPMailer\PHPMailer\?resource
var

Type(s)

\PHPMailer\PHPMailer\?resource

Error information, if any, for the last SMTP command.

error :array
var

Type(s)

array

The reply the server sent to us for HELO.

helo_rply :string|null

If null, no HELO string has yet been received.

var

Type(s)

string|null

The set of SMTP extensions sent in reply to EHLO command.

server_caps :array|null

Indexes of the array are extension names. Value at index 'HELO' or 'EHLO' (according to command that was sent) represents the server name. In case of HELO it is the only element of the array. Other values can be boolean TRUE or an array containing extension options. If null, no HELO/EHLO string has yet been received.

var

Type(s)

array|null

The most recent reply received from the server.

last_reply :string
var

Type(s)

string