Function Reference: email()
Bellow is a php.net style Function Reference for email(). The function reference is very similar to that of mail(), and most scripts should work without modification (further than the require_once() statement and prefixing the mail() directive with an e), but it is recommended that you ensure compatibility before implementation.
(PHP 4, PHP 5, require_once(email.php))
email -- Send email
Requirements
The script must call require_once("email.php") where email.php is the path name to the email.php script, at least once. It is recommended that this is just prior to the execution of email(). This example assumes that email.php is located in the same directory as the running script or on the include_path.
<?php |
Description
bool email ( string to, string subject, string message [, string additional_headers [, string additional_parameters]] )
Sends an email.
Parameters
to
Receiver or receivers of the email. The formatting of this string must comply to RFC 2822. Some examples are: user@example.com |
subject
Subject of the email to be sent.
|
||||
Note: This parameters formatting is checked, and corrected as required, but it is recommended that you follow the above rule to maintain compatibility with mail(). |
message
Message to be sent. Each line should be separated with a LF (\n). Lines should not be longer than 70 characters.
|
||
Note: This parameters formatting is checked, and corrected as required. Note: Automatic wordwrap is only available on PHP 4 >= 4.0.2 and PHP 5. Note: The full stop limitation found in mail() (on Windows) does not apply. |
||
additional_headers (optional)
String to be inserted at the end of the email header. This is typically used to add extra headers (From, Cc, and Bcc). Multiple headers should be separated by CRLF (\r\n).
|
||
Note: If no From header is added email() will create an From header based on the current domain, in the format feedback@your.domain or if available, the envelope sender specified in additional_parameters. |
||
additional_parameters (optional)
The additional_parameters parameter can be used to pass additional parameters to email(). At present the only available additional parameter is the -f parameter to set the envelope sender. See Example 3. for an example. Other additional parameters will be ignored. |
Return Values
Returns TRUE if the mail was successfully delivered, FALSE otherwise.
ChangeLog
Version |
Description |
0.9.1 |
Changed default DNS server to publicly accessible 4.2.2.1. Changed License to MIT License. |
0.9 |
Addition of $ev_verbose global variable and verbose output of the functions progress and point of failure. See Notes for further information on usage. Problems with SourceForge MX servers partially rectified by better time out management in email(). |
0.4 |
Fixed 'multiple function call' bug which caused a function redefinition error if email() was called twice from the same script. |
0.3 |
Addition of multi-address capabilities and created full functional compatibility with mail. Problem with SourceForge MX servers noted. See Notes bellow. |
0.2 |
|
Examples
Example 1. Sending mail.
Using email() to send a simple email:
<?php |
Example 2. Sending mail with extra headers.
The addition of basic headers, telling the MUA the From and Reply-To addresses:
<?php |
Example 3. Sending mail with an additional command line parameter.
The additional_parameters parameter can be used to send an additional parameter to the function.
<?php |
Example 4. Sending HTML email.
It is also possible to send HTML email with email().
<?php |
Notes
Note: Setting $esv_verbose to TRUE in the calling script cause email() to give verbose output in a similar fashion to PHP's internal Notice, Warning and Error messages, allowing monitoring of the point of faliure for each address parsed. Note: It is noted that email() has problems with SourceForge MX servers. The script will time-out if a valid email address is not provided, this problem is due to from address checks carried out by SourceForge. If more than one destination has been parsed, which includes a SourceForge email address, the script may also time out, again, due to the from address checking at the SourceForge MX servers. For more information and a better explanation of SourceForges mail policies see: http://sourceforge.net/docman/display_doc.php?docid=6695&group_id=1#et_sender_validation To minimise time-outs, it is recommended that you call the script individually for emails destined for SourceForge addresses and send a valid email address via the additional_parameters parameter; see Example 3. These problems were not noted in v e0.2 as the script could only parse one to address at a time. Note: email() takes approximately 2.5 seconds to send a single email, 4 seconds to send to 2 different addresses (in one function call) and 15-60 seconds to send a message to a SourceForge address (depending on speed of the from addresses receiving MX server). Note: It is worth noting that the email() function is not suited to larger volumes of email in a loop. This function opens and closes an SMTP socket for each email which is not very efficient. Note: Differences exist between mail() and email(), notably in additional_parameters as email() does not utilise sendmail. Please ensure that your particular application is suited before transferring from one to the other. Note: The 'bug' mentioned by the user comment dated 25-Jul-2005 08:33 on the PHP website does not affect email(). |
See Also
mail() (at http://www.php.net)