(PHP 4, PHP 5)
mail — Wysyłanie poczty elektronicznej
$do
, string $temat
, string $treść
[, string $dodatkowe_nagłówki
[, string $dodatkowe_parametry
]] )Wysyła e-mail.
do
Odbiorca lub odbiorcy e-maila.
Format tego łańcucha musi być zgodny z » RFC 2822. Oto kilka przykładów:
temat
Temat e-maila.
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.
(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łówkialbo 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.
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.
| 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ł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('osoba@example.com', '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 = 'osoba@example.com';
$subject = 'temat';
$message = 'witam';
$headers = 'From: webmaster@example.com' . "\r\n" .
'Reply-To: webmaster@example.com' . "\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('osoba@example.com', 'temat', 'wiadomość', null,
'-fwebmaster@example.com');
?>
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 = 'aidan@example.com' . ', '; // zwróćmy uwagę na przecinek
$to .= 'wez@example.com';
// 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 <mary@example.com>, Kelly <kelly@example.com>' . "\r\n";
$headers .= 'From: Birthday Reminder <birthday@example.com>' . "\r\n";
$headers .= 'Cc: birthdayarchive@example.com' . "\r\n";
$headers .= 'Bcc: birthdaycheck@example.com' . "\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.
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
donie powinien być adresem w postaci "Osoba <ktokolwiek@example.com>". 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.