Descrição

mail(
    string $to,
    string $subject,
    string $message,
    array|string $additional_headers = [],
    string $additional_params = ""
): bool

Envia um e-mail.

Parâmetros

to

Destinatário, ou destinatários do e-mail.

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

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

subject

Assunto do e-mail a ser enviado.

Cuidado

Assunto deve satisfazer a » RFC 2047.

message

Mensagem a ser enviada.

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

Cuidado

(Somente Windows) Quando o PHP está se comunicando com o servidor SMTP diretamente, e um ponto final é encontrado no início de uma linha, ela é removida. Para se defender disto, substitua estas ocorrência por dois pontos seguidos.

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

additional_headers (opcional)

String ou array a ser inserido no final do cabeçalho do e-mail.

Isto é tipicamente usado para adicionar cabeçalhos extras (From, Cc, e Bcc). Múltiplos cabeçalhos extras devem ser separados com um CRLF (\r\n). Se dados externos forem usados para compor este cabeçalho, os dados devem ser sanitizados 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:
Ao enviar e-mail, ele 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.

Se isto não foi feito, ocorrerá 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 o Return-Path ao enviar diretamente via SMTP (Windows somente).

Nota:
Se mensagens não estão sendo recebidas, tente usar somente um LF (\n). Alguns agentes Unix de transferência de e-mail (mais notavelmente » qmail) substituem LF por CRLF automaticamente (que leva à duplicação de CR se CRLF for usado). Este deve ser um último recurso, porque não está conforme a » RFC 2822.

additional_params (opcional)

O parâmetro additional_params pode ser usado para passar um parâmetro adicional para o programa configurado para usa quando enviando e-mail 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 e-mails (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 e-mail foi aceito com sucesso para entrega, false caso contrário.

É importante notar que somente pelo fato do e-mail ter sido aceito para entrega, NÃO significa que o e-mail realmente alcancará o destino esperado.

Registro de Alterações

Versão Descrição

7.2.0 O parâmetro additional_headers agora aceita um array.

Versão	Descrição
7.2.0	O parâmetro `additional_headers` agora aceita um array.

Exemplos

Exemplo #1 Enviando e-mail.

Usando mail() para enviar um simples e-mail:

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

// Se as linhas forem maiores que 70 caracteres, deve-se usar wordwrap()
$message = wordwrap($message, 70, "\r\n");

// Envia
mail('caffeinated@example.com', 'Meu Assunto', $message);
?>

Exemplo #2 Enviando e-mail com cabeçalhos extras.

A adição de cabeçalhos básicos, informando à 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 e-mail com cabeçalhos extras no formato array

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_params 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 e-mail HTML

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

<?php
// Múltiplos recipientes
$to = 'joao@example.com, susana@example.com'; // observe a vírgula

// Assunto
$subject = 'Lembrete de Aniversários para Novembro';

// Message
$message = '
<html>
<head>
  <title>Lembrete de Aniversários para Novembro</title>
</head>
<body>
  <p>Aqui estão os próximos aniversariantes de novembro!</p>
  <table>
    <tr>
      <th>Pessoa</th><th>Dia</th><th>Mês</th><th>Ano</th>
    </tr>
    <tr>
      <td>João</td><td>10</td><td>Agosto</td><td>1990</td>
    </tr>
    <tr>
      <td>Susana</td><td>17</td><td>Agosto</td><td>2003</td>
    </tr>
  </table>
</body>
</html>
';

// Para enviar e-mail HTML, o cabeçalho Content-type deve ser definido
$headers[] = 'MIME-Version: 1.0';
$headers[] = 'Content-type: text/html; charset=iso-8859-1';

// Cabeçalhos adicionais
$headers[] = 'To: Maria <maria@example.com>, Rafael <rafael@example.com>';
$headers[] = 'From: Lembrete de Aniversário <niver@example.com>';
$headers[] = 'Cc: arquivo_niver@example.com';
$headers[] = 'Bcc: verifica_niver@example.com';

// Envia o e-mail
mail($to, $subject, $message, implode("\r\n", $headers));
?>

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

Notas

Nota:
A implentação SMTP (somente Windows) de mail() difere bastante da implentação do sendmail. Primeiro, ele não usa um binário 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 analisados pelo PHP.

Desta forma, o parâmetro to não deve ser um endereço na forma de "Algo <alguem@example.com>". O comando de e-mail poderia não analisar isto adequadamente enquanto se comunica com o MTA.

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

Para enviar uma grande quantidade de e-mail, 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() - Envia email codificado
imap_mail() - Envia uma mensagem de e-mail
» PEAR::Mail
» PEAR::Mail_Mime