mail

(PHP 4, PHP 5, PHP 7, PHP 8)

mail — Envia email

Descrição

mail(
    string $to,
    string $subject,
    string $message,
    mixed $additional_headers = ?,
    string $additional_parameters = ?
): bool

Envia um email.

Parâmetros

to

Receptor, ou receptores do email.

O formato desta string precisa estar de acordo com » RFC 2822. Alguns exemplos:

user@example.com
user@example.com, anotheruser@example.com
User <user@example.com>
User <user@example.com>, Another User <anotheruser@example.com>

subject

Assunto do email a ser enviado.

Cuidado

Assunto deve satisfazer o » RFC 2047.

message

Mensagem a ser enviada.

Cada linha deve ser separada com um LF (\n). Linhas não deve ser maiores que 70 caracteres.

Cuidado

(Somente Windows) Quando PHP está usando o servidor SMTP diretamente, e uma parada total é encontrada no início de uma linha, ela é removida. Para se defender disto, substitua estas ocorrência com dois pontos seguidos.

<?php
$text = str_replace("\n.", "\n..", $text);
?>

additional_headers (opcional)

String a ser inserida no final do cabeçalho do email.

Esta é normalmente usada para adicionar cabeçalhos extras (From, Cc, e Bcc). Múltiplos cabeçalhos extra devem ser separados com um CRLF (\r\n). Se dados externos forem usados para compor este cabeçalho, os dados devem ser higienizados para que nenhum cabeçalho indesejado possa ser injetado.

Se um array for passado, suas chaves são os nomes dos cabeçalhos e seus valores são os respectivos valores dos cabeçalhos.

Nota:
Antes do PHP 5.4.42 e 5.5.27, respectivamente, additional_headers não tinha proteção de injeção de cabeçalho de email. Portanto, os usuários devem garantir que os cabeçalhos especificados sejam seguros e contenham apenas cabeçalhos. Ou seja, nunca inicie o corpo do e-mail colocando várias novas linhas.

Nota:
Quando enviando email, o email precisa conter um cabeçalho From. Este pode ser definido com o parâmetro additional_headers, ou um padrão pode ser definido no php.ini.

Um deslize fará com que resulte em uma mensagem de erro similar a Warning: mail(): "sendmail_from" not set in php.ini or custom "From:" header missing. O cabeçalho From define também Return-Path em Windows.

Nota:
Se mensagens não são recebidas, tente usar somente um LF (\n). Alguns Unix mail transfer agents (mais notavelmente » qmail) modificam LF por CRLF automaticamente (que leva a duplicação de CR se CRLF é usado). Este deve ser um último recurso, como não está de acordo com » RFC 2822.

additional_parameters (opcional)

O parâmetro additional_parameters pode ser usado para passar um parâmetro adicional para o programa configurado para usa quando enviando email usando a configuração sendmail_path. Por exemplo, isto pode ser usado para definir o endereço do envelope remetente quando usando sendmail com a opção do sendmail -f.

Este parâmetro é escapado por escapeshellcmd() internamente para prevenir a execução do comando. escapeshellcmd() impede a execução de comandos, mas permite adicionar parâmetros adicionais. Por razões de segurança, é recomendado que o usuário higienize este parâmetro para evitar adicionar parâmetros indesejados ao comando shell.

Uma vez que escapeshellcmd() é aplicada automaticamente, alguns caracteres que são permitidos como endereços de e-mail por RFCs da Internet não podem ser usados. mail() não pode permitir tais caracteres, portanto, em programas onde o uso de tais caracteres é necessário, meios alternativos de envio de emails (como o uso de um framework ou biblioteca) são recomendados.

O usuário com o qual o servidor web roda deve ser adicionado como um usuário confiável à configuração do sendmail para evitar que um cabeçalho 'X-Warning' seja adicionado à mensagem quando o remetente do envelope (-f) é definido usando este método. Para usuários do sendmail, este arquivo é /etc/mail/trusted-users.

Valor Retornado

Retorna true se o email foi aceito com sucesso para entrega, false caso contrário.

É importante notar que somente pelo o email ser aceito para entrega, não significa que o email alcancará o destino esperado.

Changelog

Versão	Descrição
7.2.0	The `additional_headers` parameter now also accepts an array.

Exemplos

Exemplo #1 Enviando email.

Usando mail() para enviar um simples email:

<?php
// The message
$message = "Line 1\r\nLine 2\r\nLine 3";

// In case any of our lines are larger than 70 characters, we should use wordwrap()
$message = wordwrap($message, 70, "\r\n");

// Send
mail('caffeinated@example.com', 'My Subject', $message);
?>

Exemplo #2 Enviando email com cabeçalhos extra.

A adição de cabeçalhos básicos, dizendo a MUA os endereços From e Reply-To:

<?php
$to      = 'nobody@example.com';
$subject = 'the subject';
$message = 'hello';
$headers = 'From: webmaster@example.com' . "\r\n" .
    'Reply-To: webmaster@example.com' . "\r\n" .
    'X-Mailer: PHP/' . phpversion();

mail($to, $subject, $message, $headers);
?>

Exemplo #3 Enviando email com um parâmetro adicional da linha de comando.

Este exemplo envia o mesmo e-mail que o exemplo imediatamente acima, mas passa os cabeçalhos adicionais como array (disponível a partir do PHP 7.2.0).

<?php
$to      = 'nobody@example.com';
$subject = 'the subject';
$message = 'hello';
$headers = array(
    'From' => 'webmaster@example.com',
    'Reply-To' => 'webmaster@example.com',
    'X-Mailer' => 'PHP/' . phpversion()
);

mail($to, $subject, $message, $headers);
?>

Exemplo #4 Enviando e-mail com um parâmetro de linha de comando adicional.

O parâmetro additional_parameters pode ser usado para passar um parâmetro adicional para o programa configurado para usar ao enviar e-mail usando o sendmail_path.

<?php
mail('nobody@example.com', 'the subject', 'the message', null,
   '-fwebmaster@example.com');
?>

Exemplo #5 Enviando email HTML

É também possível enviar email HTML com mail().

<?php
// Multiple recipients
$to = 'johny@example.com, sally@example.com'; // observa a vírgula

// Subject
$subject = 'Birthday Reminders for August';

// Message
$message = '
<html>
<head>
  <title>Birthday Reminders for August</title>
</head>
<body>
  <p>Here are the birthdays upcoming in August!</p>
  <table>
    <tr>
      <th>Person</th><th>Day</th><th>Month</th><th>Year</th>
    </tr>
    <tr>
      <td>Johny</td><td>10th</td><td>August</td><td>1970</td>
    </tr>
    <tr>
      <td>Sally</td><td>17th</td><td>August</td><td>1973</td>
    </tr>
  </table>
</body>
</html>
';

// To send HTML mail, the Content-type header must be set
$headers[] = 'MIME-Version: 1.0';
$headers[] = 'Content-type: text/html; charset=iso-8859-1';

// Additional headers
$headers[] = 'To: Mary <mary@example.com>, Kelly <kelly@example.com>';
$headers[] = 'From: Birthday Reminder <birthday@example.com>';
$headers[] = 'Cc: birthdayarchive@example.com';
$headers[] = 'Bcc: birthdaycheck@example.com';

// Mail it
mail($to, $subject, $message, implode("\r\n", $headers));
?>

Nota:
Se a intenção é enviar email HTML ou outro formato complexo, é recomendado usar o pacote PEAR » PEAR::Mail_Mime.

Notas

Nota:
A implentação do Windows de mail() difere bastante da implentação Unix. Primeiro, ele não usa um binary local para compor mensagens mas apenas opera com sockets diretos o que significa que uma MTA é necessária monitorando um socket de rede (que pode ser ou o localhost ou uma máquina remota).

Segundo, cabeçalhos customizados como From:, Cc:, Bcc: e Date: não são interpretados pela MTA, mas são analiados pelo PHP.

Assim como, o parâmetro to não deve ser um endereço na forma de "Algo <alguem@example.com>". O comando de email poderia não analisar isso adequadamente enquanto se comunica com o MTA.

Nota:
É válido notar que a função mail() não é apropriada para um grande volume de email em um loop. Esta função abre e fecha um SMTP socket para cada email, o que não é muito eficiente.

Para enviar uma grande quantidade de email, veja os pacotes » PEAR::Mail, e » PEAR::Mail_Queue.

Nota:
O seguintes RFCs podem ser úteis: » RFC 1896, » RFC 2045, » RFC 2046, » RFC 2047, » RFC 2048, » RFC 2049, e » RFC 2822.

Veja Também

mb_send_mail() - Send encoded mail
imap_mail() - Send an email message
» PEAR::Mail
» PEAR::Mail_Mime

＋add a note

User Contributed Notes 19 notes

down

Anonymous ¶

6 years ago

Security advice: Although it is not documented, for the parameters $to and $subject the mail() function changes at least \r and \n to space. So these parameters are safe against injection of additional headers. But you might want to check $to for commas as these separate multiple addresses and you might not want to send to more than one recipient.

The crucial part is the $additional_headers parameter. This parameter can't be cleaned by the mail() function. So it is up to you to prevent unwanted \r or \n to be inserted into the values you put in there. Otherwise you just created a potential spam distributor.

down

Anonymous ¶

3 years ago

If you notice wrong displayed characters in the email it's because you need to properly set the Content-Type and the Charset in the headers of the email:

<?php
$headers = 'Content-Type: text/plain; charset=utf-8' . "\r\n";
?>

Mostly, UTF-8 is your best choice.

You can set custom headers with the fourth parameter of the mail() function.

To make the whole thing waterproof, add the following header too:

<?php
$headers .= 'Content-Transfer-Encoding: base64' . "\r\n";
?>

Now you can use the combination of UTF-8 and Base64 to properly encode the subject line and the recipient name like this:

<?php
$subject = '=?UTF-8?B?' . base64_encode('Test email with German Umlauts öäüß') . '?=';
$recipient = '=?UTF-8?B?' . base64_encode('Margret Müller') . '?= <recipient@domain.com>';
?>

And don't forget to Base64 encode the email message too:

<?php
$message = base64_encode('This email contains German Umlauts öäüß.');
?>

All references are taken from:
https://dev.to/lutvit/how-to-make-the-php-mail-function-awesome-3cii

down

php at simoneast dot net ¶

6 years ago

Often it's helpful to find the exact error message that is triggered by the mail() function. While the function doesn't provide an error directly, you can use error_get_last() when mail() returns false.

<?php
$success = mail('example@example.com', 'My Subject', $message);
if (!$success) {
    $errorMessage = error_get_last()['message'];
}
?>

(Tested successfully on Windows which uses SMTP by default, but sendmail on Linux/OSX may not provide the same level of detail.)

Thanks to https://stackoverflow.com/a/20203870/195835

down

charles dot fisher at arconic dot com ¶

5 years ago

I migrated an application to a platform without a local transport agent (MTA). I did not want to configure an MTA, so I wrote this xxmail function to replace mail() with calls to a remote SMTP server. Hopefully it is of some use.

function xxmail($to, $subject, $body, $headers)
{
 $smtp = stream_socket_client('tcp://smtp.yourmail.com:25', $eno, $estr, 30);

 $B = 8192;
 $c = "\r\n";
 $s = 'myapp@someserver.com';

 fwrite($smtp, 'helo ' . $_ENV['HOSTNAME'] . $c);
  $junk = fgets($smtp, $B);

 // Envelope
 fwrite($smtp, 'mail from: ' . $s . $c);
  $junk = fgets($smtp, $B);
 fwrite($smtp, 'rcpt to: ' . $to . $c);
  $junk = fgets($smtp, $B);
 fwrite($smtp, 'data' . $c);
  $junk = fgets($smtp, $B);

 // Header 
 fwrite($smtp, 'To: ' . $to . $c); 
 if(strlen($subject)) fwrite($smtp, 'Subject: ' . $subject . $c); 
 if(strlen($headers)) fwrite($smtp, $headers); // Must be \r\n (delimited)
 fwrite($smtp, $headers . $c); 

 // Body
 if(strlen($body)) fwrite($smtp, $body . $c); 
 fwrite($smtp, $c . '.' . $c);
  $junk = fgets($smtp, $B);

 // Close
 fwrite($smtp, 'quit' . $c);
  $junk = fgets($smtp, $B);
 fclose($smtp);
}

down

imme_emosol ¶

7 months ago

Also see chunk_split (as "alternative" to wordwrap).

down

atesin > gmail ¶

7 months ago

mail() internals:

doing some tests i can say... if sendmail_path is defined in php.ini or by ini.set(), by calling function like...

mail($to, $subject, $message, $headers, $params)

would be like if php open a shell internally, execute this command, send this text to stdin, and return true if return value == 0

------------
shell> $sendmail_path $params
To: $to
Subject: $subject
$headers

$message
(EOF)
------------

in windows instead using php smtp which is very limited, i prefer to force use sendmail-like behavior, by setting sendmail_path and then use msmtp for windows

down

Mark Simon ¶

4 years ago

It is worth noting that you can set up a fake sendmail program using the sendmail_path directive in php.ini.

Despite the comment in that file, sendmail_path also works for Window. From https://www.php.net/manual/en/mail.configuration.php#ini.sendmail-path:

This directive works also under Windows. If set, smtp, smtp_port and sendmail_from are ignored and the specified command is executed.

down

Porjo ¶

13 years ago

Make sure you enclose \r\n in double quotes (not single quotes!) so that PHP can translate that into the correct linefeed code

down

chris at ocproducts dot com ¶

6 years ago

The 'sendmail' executable which PHP uses on Linux/Mac (not Windows) expects "\n" as a line separator.

This executable is a standard, and emulated by other MTAs.

"\n" is confirmed required for qmail and postfix, probably also for sendmail and exim but I have not tested.

If you pass through using "\r\n" as a separator it may appear to work, but your email will be subtly corrupted and some middleware may break. It only works because some systems will clean up your mistake.

If you are implementing DKIM be very careful, as DKIM checks will fail (at least on popular validation tools) if you screw this up. DKIM must be calculated using "\r\n" but then you must switch it all to "\n" when using the PHP mail function.

On Windows, however, you should use "\r\n" because PHP is using SMTP in this situation, and hence the normal rules of the SMTP protocol (not the normal rules of Unix piping) apply.

down

pangz dot lab at gmail dot com ¶

3 years ago

* Sending email with attachment

function sendMail(
    string $fileAttachment,
    string $mailMessage = MAIL_CONF["mailMessage"],
    string $subject     = MAIL_CONF["subject"],
    string $toAddress   = MAIL_CONF["toAddress"],
    string $fromMail    = MAIL_CONF["fromMail"]
): bool {
    
    $fileAttachment = trim($fileAttachment);
    $from           = $fromMail;
    $pathInfo       = pathinfo($fileAttachment);
    $attchmentName  = "attachment_".date("YmdHms").(
    (isset($pathInfo['extension']))? ".".$pathInfo['extension'] : ""
    );
    
    $attachment    = chunk_split(base64_encode(file_get_contents($fileAttachment)));
    $boundary      = "PHP-mixed-".md5(time());
    $boundWithPre  = "\n--".$boundary;
    
    $headers   = "From: $from";
    $headers  .= "\nReply-To: $from";
    $headers  .= "\nContent-Type: multipart/mixed; boundary=\"".$boundary."\"";
    
    $message   = $boundWithPre;
    $message  .= "\n Content-Type: text/plain; charset=UTF-8\n";
    $message  .= "\n $mailMessage";
    
    $message .= $boundWithPre;
    $message .= "\nContent-Type: application/octet-stream; name=\"".$attchmentName."\"";
    $message .= "\nContent-Transfer-Encoding: base64\n";
    $message .= "\nContent-Disposition: attachment\n";
    $message .= $attachment;
    $message .= $boundWithPre."--";
    
    return mail($toAddress, $subject, $message, $headers);
}

* Sending email in html

function sendHtmlMail(
    string $mailMessage = MAIL_CONF["mailMessage"],
    string $subject     = MAIL_CONF["subject"],
    array $toAddress    = MAIL_CONF["toAddress"],
    string $fromMail    = MAIL_CONF["fromMail"]
): bool {
    
    $to        = implode(",", $toAddress);
    $headers[] = 'MIME-Version: 1.0';
    $headers[] = 'Content-type: text/html; charset=iso-8859-1';    
    $headers[] = 'To: '.$to;
    $headers[] = 'From: '.$fromMail;    

    return mail($to, $subject, $mailMessage, implode("\r\n", $headers));
}

down

ABOMB ¶

11 years ago

I was having delivery issues from this function to Gmail, Yahoo, AOL, etc.  I used the notes here to figure that you need to be setting your Return-Path to a valid email to catch bounces.  There are two extra delivery gotchas on top of that:

1) The domain in the email used in the -f option in the php.ini sendmail parameter or in the mail() extra parameters field, needs to have a valid SPF record for the domain (in DNS as a "TXT" record type for sure and add an additional  "SPF" type record if possible).  Why? That's header field being used for spam checks.

2) You should also use a domain key or DKIM.  The trick here is that the domain key/DKIM is case sensitive!  I used Cpanel to create my domain key which automatically used all lowercase domain names in the key creation.  I found when  sending email and using a camel case "-f account@MyDomainHere.Com" option, my key was not accepted.  However it was accepted when I used "-f account@mydomainhere.com".

There are many other factors that can contribute to mail not getting to inboxes, including your own multiple failed testing attempts, so I suggest you consult each site's guidelines and don't ask me for help.  These are just the couple technical issues that helped my case.

I hope this saves someone some time and headaches...

down

Ben Cooke ¶

17 years ago

Note that there is a big difference between the behavior of this function on Windows systems vs. UNIX systems. On Windows it delivers directly to an SMTP server, while on a UNIX system it uses a local command to hand off to the system's own MTA.



The upshot of all this is that on a Windows system your  message and headers must use the standard line endings \r\n as prescribed by the email specs. On a UNIX system the MTA's "sendmail" interface assumes that recieved data will use UNIX line endings and will turn any \n to \r\n, so you must supply only \n to mail() on a UNIX system to avoid the MTA hypercorrecting to \r\r\n.



If you use plain old \n on a Windows system, some MTAs will get a little upset. qmail in particular will refuse outright to accept any message that has a lonely \n without an accompanying \r.

down

pavel.lint at vk.com ¶

11 years ago

Here's a small handy function I use to send email in UTF-8.

 <?php
function mail_utf8($to, $from_user, $from_email, 
                                             $subject = '(No subject)', $message = '')
   { 
      $from_user = "=?UTF-8?B?".base64_encode($from_user)."?=";
      $subject = "=?UTF-8?B?".base64_encode($subject)."?=";

      $headers = "From: $from_user <$from_email>\r\n". 
               "MIME-Version: 1.0" . "\r\n" . 
               "Content-type: text/html; charset=UTF-8" . "\r\n"; 

     return mail($to, $subject, $message, $headers); 
   }
?>

down

eeeugeneee ¶

6 years ago

Send mail with minimal requirements from email services.

<?php
    $encoding = "utf-8";

    // Preferences for Subject field
    $subject_preferences = array(
        "input-charset" => $encoding,
        "output-charset" => $encoding,
        "line-length" => 76,
        "line-break-chars" => "\r\n"
    );

    // Mail header
    $header = "Content-type: text/html; charset=".$encoding." \r\n";
    $header .= "From: ".$from_name." <".$from_mail."> \r\n";
    $header .= "MIME-Version: 1.0 \r\n";
    $header .= "Content-Transfer-Encoding: 8bit \r\n";
    $header .= "Date: ".date("r (T)")." \r\n";
    $header .= iconv_mime_encode("Subject", $mail_subject, $subject_preferences);

    // Send mail
    mail($mail_to, $mail_subject, $mail_message, $header);
?>

down

-2

rexlorenzo at gmail dot com ¶

11 years ago

Be careful to not put extra spaces for the $headers variable.

For example, this didn't work on our servers:

$headers = "From: $from \r\n Bcc: $bcc \r\n";

But this did:

$headers = "From: $from\r\nBcc: $bcc\r\n";

Notice the removal of the spaces around the first \r\n.

down

-2

Anonymous ¶

6 months ago

So far I used the following to make sure special charakters where correctly shown in the mail subject:

<?php $subject = '=?utf-8?B?' . base64_encode($subject) . '?='; ?>

But with very long subjects, the header line gets longer than 76 chars and some e-mail servers really don't like that... So this is my new solution:

<?php $subject = substr(mb_encode_mimeheader("Subject: " . $subject, 'utf-8', 'B', "\r\n", 0), 9); ?>

Please note: I added "Subject: " in front of $subject and stripped it of afterwards. This is to make sure, that the necessarry space is reserved, as PHP will add the "Subject: " itself...

down

-9

Max AT ¶

11 years ago

To define a mail sensitivity you have to put this line in the headers:

<?php
        $headers = "MIME-Version: 1.0\n" ;
        $headers .= "Content-Type: text/html; charset=\"iso-8859-1\"\n";

        $headers .= "Sensitivity: Personal\n";

 $status   = mail($to, $subject, $message,$headers);
?> 

Possible Options:
Sensitivity: Normal, Personal, Private and Company-Confidential

These will be recognised and handled in Outlook, Thunderbird and others.

down

-5

andrew at my-syte dot com ¶

10 months ago

Regarding To: 

be careful not to duplicate To in the additional_headers, 

lest gmail already flags it thus:

host gmail-smtp-in.l.google.com [142.251.xx.xx]
SMTP error from remote mail server after end of data:
550-5.7.1 [xxx.xxx.xx.xx] This message is not RFC 5322 compliant, the issue is:
550-5.7.1 duplicate To headers. To reduce the amount of spam sent to Gmail,
550-5.7.1 this message has been blocked. Please review
550 5.7.1 RFC 5322 specifications for more information.

down

-32

php dot net at schrecktech dot com ¶

18 years ago

When sending MIME email make sure you follow the documentation with the "70" characters per line...you may end up with missing characters...and that is really hard to track down...

＋add a note