PHP Classes

PHP Mail Sending: Send HTML email messages with attachments

Recommend this page to a friend!
  Info   Documentation   View files Files   Install with Composer Install with Composer   Download Download   Reputation   Support forum   Blog    
Ratings Unique User Downloads Download Rankings
StarStarStarStar 70%Total: 645 This week: 1All time: 4,960 This week: 34Up
Version License PHP version Categories
php-mail-sending 1.0.2GNU General Publi...5.5HTML, Email, PHP 5
Description 

Author

This class can send HTML email messages with attachments.

It can compose HTML email messages with an alternative text part. If the text alternative is missing, it will extract the text from the HTML.

Messages can embed images and attachment files.

Recipients can be defined for "To", "CC" or "BCC" headers.

Picture of Christian Vigh
  Performance   Level  
Name: Christian Vigh <contact>
Classes: 32 packages by
Country: France France
Age: 58
All time rank: 13410 in France France
Week rank: 6 Up1 in France France Up
Innovation award
Innovation award
Nominee: 20x

Winner: 3x

Documentation

CONTENTS OF THE EXAMPLES DIRECTORY

File examples.inc.php

This is the main include file for all the example. You will have to redefine two variables here before trying to run the examples :

  • $recipient (mandatory) : each example script is sending an email to a recipient. This is the variable used for that, so redefine it to specify your own email address.
  • $sender (optional) : the sender's email address, which can be a completely invented address. Specify false if you want to use the sendmail_from setting from your php.ini file.

Directory data/

Contains files that are used as attachments by the attachments.Php example script.

Directory Images/

Contains two images that are embedded in the html contents of several example scripts.

File mail.html

Html file that contains mail contents used by the external-html.php example script.

Example scripts

textonly.php

Sends an email with only a text part (no html contents).

text-and-html.php

Sends an email with both text and html parts.

embedded-images.php

Sends an email containing embedded images. Html contents are given by a string.

external-html.php

Sends an email whose html contents come from an external file, mail.html. The html contents reference two embedded images.

attachments.php

Sends an email with embedded images and attachments (coming from the data/ directory).


Details

INTRODUCTION

The Mail class is yet-another PHP mailer, with the following features :

  • It entirely relies on the PHP mail() function, meaning that it will be automatically integrated into your production environment, using your hp.ini settings
  • It allows you to specify both plain text and html parts, for messenging clients which cannot read html
  • It automatically embeds images referenced by your html code, coming either from a string or from an external html file.
  • It allows you to add as many file attachments as you want.
  • You can of course specify "To", "CC" or "BCC" recipients. The class will ignore any duplicates.

DEPENDENCIES

The Mail* class requires the Adavanced Regex package, located here :

http://www.phpclasses.org/package/9336-PHP-Match-MSDOS-UNIX-patterns-with-regular-expressions.html

File Regex.class.php has been provided here for your convenience, but this may not be the latest version.

EXAMPLES

You can have a look at the examples/ directory, to have an overview of the various usages of this class. The file examples/README.md explains how the examples are organized, and which example does what.

The basic usage of the Mail class is fairly simple ; the following example will send a plain text mail with subject "Mail subject", and contents "Mail contents", to the address "someone@example.com" :

$mail 	=  new Mail ( false, "someone@example.com", "Mail subject", "Mail contents" ) ;
$mail -> Send ( ) ;

An exception will be thrown if something goes wrong.

REFERENCE

METHODS

Constructor

The Mail class constructor has the following signature :

$mail 	=  new Mail ( $from = false, $to = false, $subject = false, $text = false, $html = false, $html_base = false ) ;

It creates an instance of the class, and any parameters defined in the constructor can be specified later by using properties.

Parameters are the following

  • $from : Sender's email. It can be anything if your outgoing smtp server does not check the validity of the sender's email address, which is a common case on self-configured Unix systems. If you do not specify a value for this parameter, then you will have two choices : - Either set it later by assigning the From property, or - Let PHP use your settings defined in php.ini (sendmail_from setting)
  • to : Either a string specifying the recipient's email, or an array of strings specifying multiple recipients. If you do not specify this parameter during object instantiation, you will still be able to specify recipients using the AddRecipient() method.
  • $subject : Mail subject. You can specify it later by assigning the Subject property.
  • $text : Plain text contents. You can specify it later by assigning the Text property. If no contents are provided for this value, then plain text contents will be extracted from the Html property.
  • $html : Html contents. You can specify it later by assigning the Html property.
  • $html\_base : The class automatically detects references to external images and embeds them in the outgoing mail. This parameter specifies the root path for the images. You can set it later by assigning the HtmlBasePath* property.

$mail -> AddRecipient ( $addresses... )

Adds the specified addresses to the recipient list.

The function's parameters can be any number of strings or arrays of strings containing the addresses.

Duplicate addresses will be ignored.

Example :

$mail -> AddRecipient ( 'me@example.com', [ 'person1@example.com', 'person2@example.com' ] ) ;

You can also manually append addresses to the To property but in this case, there will be no checking on duplicates :

$mail -> To [] 		=  'me@example.com' ;
$mail -> To [] 		=  'person1@example.com' ; 	// etc.

$mail -> AddCC ( $addresses... )

Adds addresses to Carbon Copy recipients.

Behaves as the AddRecipient() method. You can also manually append addresses to the CC property.

$mail -> AddBCC ( $addresses... )

Adds addresses to Blind Carbon Copy recipients (ie, the recipients added by the AddRecipient() and AddCC() methods won't know that there are additional recipients specified as BCC).

Behaves as the AddRecipient() method. You can also manually append addresses to the BCC property.

$mail -> AddMimeHeader ( $name, $value, $replace = true ) ;

Adds a MIME header or replaces an existing one.

$mail -> AddAttachment ( $path, $name = false )

Adds an attachment to the current mail. The $name parameter indicates the attachment file name that will be shown to the recipient when he will open its mail. If not specified, the filename portion of the $path parameter will be used.

$contents = $mail -> GetContents ( ) ;

Returns the mail contents as plain text, including MIME headers, text and base64-encoded attachments.

$mail -> LoadHtml ( $file, $base\_path = false ) ;

Html contents can be specified in two ways : either by specifying some value for the $html parameter of the class constructor, or setting later the Html property.

The LoadHtml() method provides a third way to load html contents, from an external file. This file can be a regular html page using <html>, <head> and <body> tags (or not) ; the following contents will be extracted from it to form the mail's html part :

  • Any &lt;style&gt; contents located between the &lt;head&gt; and &lt;/head&gt; tags
  • Any contents located between the &lt;body&gt; and &lt;/body&gt; tags

The $base\_path parameter indicates the root path for searching external images referenced by html contents.

$mail -> Send ( ) ;

Sends the mail using the standard PHP mail() function.

An exception will be thrown if something goes wrong.

$mail -> Validate ( ) ;

Validates an email by verifying the following elements :

  • At least one recipient must have been specified
  • The email originator must have been specified

It also provides default values for certain fields :

  • If the Subject property is empty, it will be set to "(No subject)"
  • If the ReplyTo and ErrorsTo properties are empty, they will be set to the email originator.
  • If the HTML content part is empty but not the text content part, HTML contents will be set to text contents (or vice-versa).
  • If both content parts are empty, the string "\\\EMPTY MESSAGE \\\" will be inserted.

PROPERTIES

BCC

An array containing the Blind Carbon Copy recipients.

The preferred way of adding new BCC recipients is by using the AddBCC() method, which performs additional checkings, such as ignoring duplicate addresses.

CC

An array containing the Carbon Copy recipients.

The preferred way of adding new CC recipients is by using the AddCC() method, which performs additional checkings, such as ignoring duplicate addresses.

DestinatioCharset

MIME character set used for building mail contents. The default is ISO8859-1.

ErrorsTo

Email address where error messages coming from mail servers will be sent.

From

Sender's email address.

Html

Html part of the mail contents.

HtmlBasePath

Base path to be used for retrieving images referenced by the html contents.

ReplyTo

Email address to be used when the recipient will reply to the mail.

ReturnPath

Email address for the return path.

ReturnReceiptTo

Email address to be used for read receipts.

SourceCharset

Character set used in the source html contents.

Subject

Mail subject.

Text

Plain text part of the message contents.

To

An array containing the list of recipients.

The preferred way of adding new recipients is by using the AddRecipient() method, which performs additional checkings, such as ignoring duplicate addresses.


  Files folder image Files (17)  
File Role Description
Files folder imageexamples (8 files, 2 directories)
Accessible without login Plain text file LICENSE Lic. License text
Plain text file Mail.phpclass Class Class source
Accessible without login Plain text file NOTICE Data Auxiliary data
Accessible without login Plain text file README.md Doc. Documentation
Plain text file Regex.class.php Class Class source

  Files folder image Files (17)  /  examples  
File Role Description
Files folder imagedata (2 files)
Files folder imageimages (2 files)
  Accessible without login Plain text file attachments.php Example Example script
  Accessible without login Plain text file embedded-images.php Example Example script
  Accessible without login Plain text file examples.inc.php Aux. Auxiliary script
  Accessible without login Plain text file external-html.php Example Example script
  Accessible without login HTML file mail.html Data Auxiliary data
  Accessible without login Plain text file README.md Doc. Documentation
  Accessible without login Plain text file text-and-html.php Example Example script
  Accessible without login Plain text file textonly.php Example Example script

  Files folder image Files (17)  /  examples  /  data  
File Role Description
  Accessible without login Plain text file file1.txt Doc. Documentation
  Accessible without login Plain text file file2.txt Doc. Documentation

  Files folder image Files (17)  /  examples  /  images  
File Role Description
  Accessible without login Image file image1.jpg Icon Icon image
  Accessible without login Image file image2.jpg Icon Icon image

The PHP Classes site has supported package installation using the Composer tool since 2013, as you may verify by reading this instructions page.
Install with Composer Install with Composer
 Version Control Unique User Downloads Download Rankings  
 100%
Total:645
This week:1
All time:4,960
This week:34Up
User Ratings User Comments (1)
 All time
Utility:91%StarStarStarStarStar
Consistency:91%StarStarStarStarStar
Documentation:83%StarStarStarStarStar
Examples:75%StarStarStarStar
Tests:-
Videos:-
Overall:70%StarStarStarStar
Rank:239
 
Thats a good class, nice job ;-)
7 years ago (José Filipe Lopes Santos)
80%StarStarStarStarStar