Mail::factory()

Mail::factory() – creates a mailer instance

Synopsis

require_once 'Mail.php';

object &factory ( string $backend , array $params = array() )

Description

Creates a instance of a backend-specific mailer class.

Parameter

  • string $backend - the name of the backend "mail","smtp", "sendmail"

  • array $params - a array of backend specific parameters.

    List of parameter for the backends

    • mail

      • If safe mode is disabled, $params will be passed as the fifth argument to the PHP mail() function. If $params is an array, its elements will be joined as a space-delimited string.

    • sendmail

      • $params["sendmail_path"] - The location of the sendmail program on the filesystem. Default is /usr/bin/sendmail.

      • $params["sendmail_args"] - Additional parameters to pass to the sendmail. Default is -i.

    • smtp

      • $params["host"] - The server to connect. Default is localhost.

      • $params["port"] - The port to connect. Default is 25.

      • $params["auth"] - Whether or not to use SMTP authentication. Default is FALSE.

      • $params["username"] - The username to use for SMTP authentication.

      • $params["password"] - The password to use for SMTP authentication.

      • $params["localhost"] - The value to give when sending EHLO or HELO. Default is localhost

      • $params["timeout"] - The SMTP connection timeout. Default is NULL (no timeout).

      • $params["verp"] - Whether to use VERP or not. Default is FALSE.

      • $params["debug"] - Whether to enable SMTP debug mode or not. Default is FALSE.

        Mail internally uses Net_SMTP::setDebug .

      • $params["persist"] - Indicates whether or not the SMTP connection should persist over multiple calls to the send() method.

      • $params["pipelining"] - Indicates whether or not the SMTP commands pipelining should be used.

Return value

object - a specific Mail instance or a PEAR_Error object on failure.

Throws

Possible PEAR_Error values
Error code Error message Reason Solution
NULL "Unable to find class for driver xxx" Mailer backend class was not found. Check the $backend parameter, if correct reinstall and/or update your Mail package.

Note

This function should be called statically.

How to send a mail and the mailer backends (Previous) sends a mail (Next)
Last updated: Sat, 16 Feb 2019 — Download Documentation
Do you think that something on this page is wrong? Please file a bug report.
View this page in:
  • English

User Notes:

Note by: sergiomb
2016-08-23 20:50 UTC
The undocumented parameter: socket_options , let me authenticate when I got this error:
authentication failure [SMTP: STARTTLS failed (code: 220, response: TLS go ahead)]

I just need add :
'auth' => "PLAIN",
'socket_options' => array('ssl' => array('verify_peer_name' => false)),

Note by: mihai@avanticart.ro
2015-11-09 17:10 UTC
There should be an option to set the SSL context options (eg: verify_peer, verify_pear_name, cafile, etc).

As of PHP 5.6, the verify_peer options is set to true: http://php.net/manual/en/migration56.openssl.php

Note by: jay@mosio.com
2012-10-04 20:43 UTC
I was having trouble with XVERP being added in the SMTP connection even though $params["verp"] was FALSE.

The fix is to NOT set $params["verp"] at all, either unset it or just don't specify it in your $params.

$params["verp"] = FALSE; // comment out this line if you see an XVERP error
$params["debug"] = TRUE;
...
$smtp = Mail::factory('smtp', $params);

Calling $smtp->send() gives the following debugging:
DEBUG: Send: MAIL FROM:<---@---.com> XVERP
DEBUG: Recv: 555 5.5.4 Unsupported option: XVERP
DEBUG: Send: RSET

PEAR::isError($mail) outputs:
Failed to set sender: ---@---.com [SMTP: Invalid response code received from server (code: 555, response: 5.5.4 Unsupported option: XVERP)]
Note by: noyearzero@hotmail.com
2011-05-13 21:39 UTC
If you are using 'mail' as your backend and you want to set your Return-Path you can do it like:

$mail_object =& Mail::factory('mail', '-f bounce@domain.com') ;

Then later if you need to change it you can

$mail_object->_params = '-f bounce2@domain.com' ;

This is useful if you use a function to send your email since you can't create a new reference to the factory inside a function. But keep in mind that your new _params will be used for all subsequent calls to your $mail_object. So you may want to manually set them every time you send an email.
Note by: carpet@awesomedesigns.co.uk
2011-01-20 12:10 UTC
If you are using the smtp backend and an SMTP server that requires authentication and you want to use a method other than PLAIN or LOGIN (such as CRAM-MD5) you'll need to make sue you've got Pear's Auth_SASL package installed as well, as it isn't made obvious from the error messages that Mail returns why it's failing!
Note by: ruediger.schmidt@bam.de
2010-10-06 09:04 UTC
Set headers for UTF-8:
$headers['Content-Type'] = "text/plain; charset=\"UTF-8\"";
$headers['Content-Transfer-Encoding'] = "8bit";
Note by: satsilem@gmail.com
2010-02-23 19:29 UTC
Still can't figure out how to send proper UTF 8 emsils.... any ideas?
Note by: paulovitorbal@gmail.com
2009-12-31 23:58 UTC
the persist value should be TRUE or FALSE. it's not clear on the page.

if you are getting the error:
Failed to connect to smtp.example.com.br:25 [SMTP: Invalid response code received from server (code: 421, response: 4.7.0 smtp.example.com Error: too many connections from your_ip)]

try to get this option to TRUE.
Note by: Joe
2009-06-29 14:17 UTC
There is hard-coded -f option in Mail_sendmail->send so it is impossible to set it using $params['sendmail_args']. It is hard-coded to -f$from.

In my case it caused 'X-Authentication-Warning' in mail headers.
Note by: shaun@shaunfreeman.co.uk
2009-04-29 23:57 UTC
When sending mail via smtp be careful with the $params["auth"] option, the docs say it set it either to true or false, but in my case this didn't work and only when I set it to the actual authentication method of the server it worked. In my case I had to set it to:

$params["auth"] = "PLAIN";

This little problem had me going around in circles for 2 weeks!