Wysyłanie poczty elektronicznej

Opis

bool mail ( string $do , string $temat , string $treść [, string $dodatkowe_nagłówki [, string $dodatkowe_parametry ]] )

Wysyła e-mail.

Parametry

do

Odbiorca lub odbiorcy e-maila.

Format tego łańcucha musi być zgodny z » RFC 2822. Oto kilka przykładów:

[email protected]
[email protected], [email protected]
Osoba <[email protected]>
Osoba <[email protected]>, Inna osoba <[email protected]>

temat

Temat e-maila.

Uwaga

Temat musi spełniać » RFC 2047.

treść

Treść wiadomości.

Każdy wiersz tekstu powinien być zakończony znakiem końca linii LF (\n). Wiersze nie powinny zawierać więcej niż 70 znaków.

Uwaga

(Tylko dla Windows) Kiedy PHP łaczy się bezpośrednio do serwera SMTP i zostaną znalezione znaki wskazujące na koniec wiadomości (\n.) to zostaną one usunięte, co spowoduje że wiadomość będzie mało czytelna. Aby temu zapobiec, należy dodać dodatkową kropkę.


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

dodatkowe_nagłówki (opcjonalnie)

Łańcuchy znaków dodane na końcu nagłówka e-maila.

Parametr jest zazwyczaj wykorzystywany do wstawienia dodatkowych nagłówków (From, Cc, oraz Bcc). Dodatkowe nagłówki rozdziela się za pomocą znaku powrotu karetki i nowego wiersza - CRLF (\r\n).

Informacja:
Każdy e-mail musi zawierać nagłówek From. Można go podawać jako parametr dodatkowe_nagłówki albo ustawić w pliku php.ini.

Wynikiem pominięcia tego nagłówka będzie informacja o błędzie, podobna do tej: Warning: mail(): "sendmail_from" not set in php.ini or custom "From:" header missing. W Windows nagłówek From ustawia także Return-Path.

Informacja:
Jeśli wiadomości nie są dostarczane, można spróbować używać tylko znaku LF (\n). Niektóre, gorzej napisane MTA na systemy Unix zamieniają automatycznie LF na CRLF (co powoduje podwojenie CR jeśli zostało użyte CRLF). Powinno się to zrobić w ostateczności, jako że nie jest to zgodne z dokumentem » RFC 2822.

dodatkowe_parametry (opcjonalne)

Parametr dodatkowe_parametry może być użyty do przekazania dodatkowych opcji do programu wysyłającego e-maile. Zostaną one użyte przy wysyłaniu e-maila w ścieżce sendmaila jako ustawienia konfiguracyjne. Mogą one być użyte na przykład do wprowadzenia adresu e-mail nadawcy, tak jakbyśmy użyli polecenia sendmail z opcją -f.

Użytkownik z którego prawami jest uruchomiony serwer WWW powinien być dodany jako zaufany użytkownik w konfiguracji programu sendmail, aby zapobiec dodawania nagłówka 'X-Warning' do wiadomości, kiedy ustawiany jest adres nadawcy (-f). Dla użytkowników programu sendmail jest to plik /etc/mail/trusted-users.

Zwracane wartości

Zwraca TRUE jeśli e-mail został zaakceptowany do wysłania, w przeciwnym przypadku zwraca FALSE.

Ważną informacją jest to, że pomimo iż e-mail został zaakceptowany do wysłania, to NIE oznacza, że będzie on już w tej chwili wysyłany do odbiorców.

Rejestr zmian

Wersja	Opis
4.3.0 (tylko Windows)	Obsługiwane są wszystkie dodatkowe nagłówki (takie jak From, Cc, Bcc i Date) i nie są w nich rozróżniane małe i duże litery. (dodatkowe nagłówki nie były przetwarzane bezpośrednio przez MTA, tylko wcześniej parsowane za pomocą PHP, a PHP < 4.3 obsługiwał tylko nagłówek Cc i rozróżniał małe i duże litery).
4.2.3	Parametr `dodatkowe_parametry` jest wyłączony w trybie safe_mode, a funkcja mail() wywołuje stosowny komunikat i zwraca `FALSE` w czasie próby jego użycia.
4.0.5	Dodano parametr `dodatkowe_parametry`.

Przykłady

Przykład #1 Wysłanie e-maila.

Użycie funkcji mail() do wysłania prostej wiadomości:


<?php
// Wiadomość
$message = "Linia 1\nLinia 2\nLinia 3";

// W przypadku każdej linii dłuższej niż 70 znaków powinniśmy użyć funkcji wordwrap()
$message = wordwrap($message, 70);

// Wyślij
mail('[email protected]', 'Temat wiadomości', $message);
?>

Przykład #2 Wysłanie e-maila z dodatkowymi nagłówkami.

Dodatkowe, podstawowe nagłówki informują program klienta poczty (MUA) o adresach From i Reply-To:


<?php
$to      = '[email protected]';
$subject = 'temat';
$message = 'witam';
$headers = 'From: [email protected]' . "\r\n" .
    'Reply-To: [email protected]' . "\r\n" .
    'X-Mailer: PHP/' . phpversion();

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

Przykład #3 Wysłanie e-maila z dodatkowym parametrem wiersza poleceń.

Parametr dodatkowe_parametry może być użyty do przekazania dodatkowych opcji do programu wysyłającego e-maile. Zostaną one użyte przy wysyłaniu e-maila w ścieżce sendmaila.


<?php
mail('[email protected]', 'temat', 'wiadomość', null,
   '[email protected]');
?>

Przykład #4 Wysłanie e-maila w formacie HTML

Za pomocą mail() możliwe jest wysłanie maila z treścią w formacie HTML.


<?php
// kilku odbiorców
$to  = '[email protected]' . ', '; // zwróćmy uwagę na przecinek
$to .= '[email protected]';

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

// wiadomość
$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>Joe</td><td>3rd</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>
';

// Aby wysłać e-mail HTML, musi być ustawiony nagłówek Content-type
$headers  = 'MIME-Version: 1.0' . "\r\n";
$headers .= 'Content-type: text/html; charset=iso-8859-1' . "\r\n";

// Dodatkowe nagłówki
$headers .= 'To: Mary <[email protected]>, Kelly <[email protected]>' . "\r\n";
$headers .= 'From: Birthday Reminder <[email protected]>' . "\r\n";
$headers .= 'Cc: [email protected]' . "\r\n";
$headers .= 'Bcc: [email protected]' . "\r\n";

// Wysłanie e-maila
mail($to, $subject, $message, $headers);
?>

Informacja:
Jeśli mamy zamiar wysyłać HTML albo e-maile o złożonej zawartości, zaleca się użyć pakietu PEAR » PEAR::Mail_Mime.

Notatki

Informacja:
Implementacja funkcji mail() w systemach Windows różni się pod wieloma względami od implementacji na platformach Unix. Po pierwsze, do tworzenia wiadomości funkcja nie używa lokalnych poleceń systemowych, tylko operuje bezpośrednio na gniazdach. To oznacza, że wymagana jest dodatkowa usługa MTA, nasłuchująca na porcie (która może działać na localhost lub maszynie zdalnej).

Po drugie, dodatkowe nagłówki, takie jak From:, Cc:, Bcc: i Date: nie są przetwarzane przez MTA, tylko parsowane za pomocą PHP.

Parametr do nie powinien być adresem w postaci "Osoba <[email protected]>". Polecenie mail może nie parsować tego właściwie, podczas komunikowania się z MTA.

Informacja:
Nie warto używać funkcji mail() do wysyłania dużej ilości e-maili stosując pętle. Ta funkcja otwiera i zamyka gniazdo SMTP dla każdego wysyłanego e-maila, a to jest mało wydajne.

Do wysyłania dużej ilości e-maili można stosować pakiety » PEAR::Mail, i » PEAR::Mail_Queue.

Informacja:
Poniższe dokumenty RFC mogą być pomocne: » RFC 1896, » RFC 2045, » RFC 2046, » RFC 2047, » RFC 2048, » RFC 2049, i » RFC 2822.

Zobacz też:

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