Close Menu

    PHPMailer Properties Reference

    0
    By on PHPMailer

    Every public property of PHPMailer 6.x you are likely to set, with its type, default and what it actually changes. Properties are set directly on the instance — there are no setters for most of them:

    $mail->Host    = 'smtp.example.com';
$mail->Port    = 587;
$mail->CharSet = PHPMailer::CHARSET_UTF8;

    SMTP connection

    Property Type Default Purpose
    $Host string localhost SMTP server. Multiple hosts can be given semicolon-separated as a failover list.
    $Port int 25 Set to 587 for STARTTLS, 465 for implicit TLS.
    $SMTPSecure string '' ENCRYPTION_STARTTLS (tls) or ENCRYPTION_SMTPS (ssl).
    $SMTPAuth bool false Enable authentication. Needed for every hosted provider.
    $Username string '' Sometimes the full address, sometimes the local part. Providers differ.
    $Password string '' Read it from the environment, not from source.
    $AuthType string '' Forces a mechanism: LOGIN, PLAIN, CRAM-MD5, XOAUTH2. Auto-detected when empty.
    $SMTPAutoTLS bool true Upgrade to TLS whenever the server advertises STARTTLS. Leave on.
    $SMTPKeepAlive bool false Reuse one connection across sends. Call smtpClose() when done.
    $Timeout int 300 Seconds. The RFC default, far too long for a web request — lower it.
    $SMTPOptions array [] Stream context options, mainly SSL. See the warning below.
    $Helo string '' Hostname sent in EHLO. Defaults to $Hostname.
    $Hostname string '' Used in Message-ID and Received. Falls back to the server hostname.

    On $SMTPOptions: the snippet that disables verify_peer circulates widely as a fix for certificate errors. It works by turning off the verification TLS exists to provide. Fix the CA bundle instead — openssl.cafile in php.ini. Disabling verification against a production server means any machine on the path can read the credentials you are about to send.

    Debugging

    Property Type Default Purpose
    $SMTPDebug int 0 SMTP::DEBUG_OFF … DEBUG_LOWLEVEL (0–4). Use 2 to diagnose, 0 in production.
    $Debugoutput string\|callable echo echo, html, error_log, or a callable receiving ($str, $level). 
    $mail->Debugoutput = function ($str, $level) {
    error_log('PHPMailer: ' . trim($str));
};

    Sender and recipients

    Property Type Default Purpose
    $From string root@localhost Visible From. Set via setFrom() rather than directly.
    $FromName string Root User Display name.
    $Sender string '' Envelope sender / Return-Path — where bounces go. Separate from From.
    $ConfirmReadingTo string '' Read-receipt address. Most clients ignore or prompt.
    $SingleTo bool false Send a separate message per To recipient so none sees the others.
    $do_verp bool false Variable envelope return path, for per-recipient bounce tracking.

    $Sender is worth setting deliberately. Bounces go to the envelope sender, so pointing it at a monitored mailbox is how you learn which addresses are dead — rather than sending to them forever and eroding your reputation.

    Content

    Property Type Default Purpose
    $Subject string '' Subject line.
    $Body string '' Main body: HTML if isHTML(true), otherwise plain text.
    $AltBody string '' Plain-text alternative. Always set it for HTML mail.
    $CharSet string iso-8859-1 Set to PHPMailer::CHARSET_UTF8 for anything not pure ASCII.
    $ContentType string text/plain Managed by isHTML().
    $Encoding string 8bit 7bit, 8bit, base64, binary, quoted-printable.
    $WordWrap int 0 Wrap plain text at N characters. 78 is the conventional value.
    $Ical string '' An iCalendar event body, sent as an alternative part.
    $AllowEmpty bool false Permit an empty body instead of failing.

    The $CharSet default catches everyone eventually. ISO-8859-1 cannot represent an em dash, a curly quote, or any non-Latin script, and the result is mojibake in the recipient’s client. Set UTF-8 unless you have a specific reason not to.

    Headers and metadata

    Property Type Default Purpose
    $Priority ?int null 1 high, 3 normal, 5 low. Aggressive values can hurt filtering.
    $MessageID string '' Override the generated Message-ID. Must be RFC-conformant.
    $MessageDate string '' Override the Date header.
    $XMailer string '' Overrides the X-Mailer header. Set to a single space to remove it entirely.
    $Version string — Read-only library version.
    $ErrorInfo string '' The last error, including the server’s own text. Log this, not the exception message.

    DKIM

    Property Type Purpose
    $DKIM_domain string Signing domain, normally the From domain.
    $DKIM_selector string Selector; the key lives at <selector>._domainkey.<domain>.
    $DKIM_private string Path to the private key. Keep it outside the web root.
    $DKIM_private_string string The key as a string, for secret-manager setups.
    $DKIM_passphrase string Passphrase, if the key is encrypted.
    $DKIM_identity string Identity in the signature; usually $From.
    $DKIM_extraHeaders array Additional headers to include in the signature.
    $DKIM_copyHeaderFields bool Copy signed headers into the signature. Rarely needed. 
    $mail->DKIM_domain   = 'example.com';
$mail->DKIM_selector = 'phpmailer';
$mail->DKIM_private  = '/secure/dkim_private.pem';
$mail->DKIM_identity = $mail->From;

    Transport

    Property Type Default Purpose
    $Mailer string mail mail, smtp, sendmail, qmail. Set by the is*() methods.
    $Sendmail string /usr/sbin/sendmail Path to the binary. Use -bs so you get real status back.
    $UseSendmailOptions bool true Pass -f for the sender. Disable for non-sendmail-compatible MTAs.
    $action_function string '' Callback invoked after each send, receiving result, recipients, subject and body.

    Constants worth knowing

    Constant Value
    PHPMailer::CHARSET_UTF8 utf-8
    PHPMailer::CHARSET_ISO88591 iso-8859-1
    PHPMailer::CHARSET_ASCII us-ascii
    PHPMailer::ENCRYPTION_STARTTLS tls
    PHPMailer::ENCRYPTION_SMTPS ssl
    PHPMailer::ENCODING_BASE64 base64
    PHPMailer::ENCODING_QUOTED_PRINTABLE quoted-printable
    PHPMailer::ENCODING_8BIT 8bit
    SMTP::DEBUG_OFF … DEBUG_LOWLEVEL 0 … 4

    Prefer the constants to their string values. They are self-documenting, and a typo in 'startls' fails at runtime while ENCRYPTION_STARTLS fails immediately.

    A sane baseline

    $mail = new PHPMailer(true);

$mail->isSMTP();
$mail->Host       = getenv('SMTP_HOST');
$mail->Port       = 587;
$mail->SMTPSecure = PHPMailer::ENCRYPTION_STARTTLS;
$mail->SMTPAuth   = true;
$mail->Username   = getenv('SMTP_USER');
$mail->Password   = getenv('SMTP_PASS');
$mail->Timeout    = 30;
$mail->CharSet    = PHPMailer::CHARSET_UTF8;
$mail->XMailer    = ' '; // omit the X-Mailer header
$mail->Sender     = 'bounces@example.com';

    Rather than repeating this everywhere, put it in a subclass — see Extending PHPMailer.

    See also

    sunshyne works on technical SEO and email deliverability for French-speaking markets, and runs the digital consultancy at sunshyne.ch. Most of that work sits where the two overlap. On the SEO side: redirect mapping, crawl and indexation diagnostics, server log analysis, and recovering domains whose history has damaged them. On the email side: the authentication layer — SPF, DKIM and DMARC — sender reputation, and the reasons a technically valid message still gets filtered. These PHPMailer pages exist because the second half of that work keeps returning to the same questions: which transport to use, why an SMTP connection fails, and why a correctly formed message is rejected anyway. The examples here are the ones worth keeping after answering those questions more than once.

    Related Posts

    Comments are closed.