MIME_Mail.class.php

class MIME_Mail (version 1.0rc4)

MIME_Mail is a class for easy creation and manipulation of multipart-mail-massages. You can add attachments, specify multiple recipients, check for the correct spelling of email-addresses and last but not least send the message.

Installation

1) Download MIME_Mail
2) Uncomress with: tar -xvzf mime_mail.class.php.tar.gz
3) Just move the file mime_mail.class/mime_mail.class.php to your PHP-include-directory or move it to your webtree. Then include (or require) the file in your PHP-application. That's all.

Create new MIME_Mail-Object

include( "mime_mail.class.php" );
$mime = new MIME_Mail;

Method Documentation

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

addAttachment( $at_content, $at_name, $at_type, $at_encoding, $cid = "", $disposition = "" )

Adds the string $at_content as attachment to the mail-object. The string will be attached as file $at_name. The filetype of the attachment can be specified with $at_type. If omitted, this method tries to figure out the filetype from the suffix of the filename, specified via $at_name. If recognition fails, the file-type defaults to "text/plain".

The encoding of the string can be specified with $at_encoding. If omitted, $at_encoding defaults to "us-ascii".

You can also specify a "Content-ID" with the $cid-parameter. This gives you the opportunity to reference this file in the HTML-part of your MIME-mail.

The $disposition-parameter describes the "Content-Disposition" of the attachment. If left empty and if the $cid-parameter is set, then the "Content-Disposition" will be set to "inline". Some mail-clients will display the attached file in the mail-body. If you do not want the attachment to be displayed "inline", you can set the $disposition-parameter to "attachment".

Returns true on success, false otherwise. You can check the error with getErrorCode and getErrorMsg.

See also: addFile, setHTMLPart

Example:

include( "mime_mail.class.php" );
$mime = new MIME_Mail;

$text = "This is the attachment-text.\nA file with two lines.";
$name = "test.txt";
$type = "text/plain";
$enc = "iso-8859-1";

$mime->addAttachment( $text, $name, $type, $at_encoding, "" );

addBcc( $bcc_email, $bcc_name = "" )

Adds an address to the BCC-field of the mail-object. $bcc_email specifies the email-address, $bcc_name specifies the name of the recipient.

See also: addCc, addTo

Example:

include( "mime_mail.class.php" );
$mime = new MIME_Mail;

$mime->addBcc( "doe@domain.com", "John Doe" );
$mime->addBcc( "jane.doe@domain.org" );

addCc( $cc_email, $cc_name = "" )

Adds an address to the CC-field of the mail-object. $cc_email specifies the email-address, $cc_name specifies the name of the recipient.

See also: addTo, addBcc

Example:

include( "mime_mail.class.php" );
$mime = new MIME_Mail;

$mime->addCc( "doe@domain.com", "John Doe" );
$mime->addCc( "jane.doe@domain.org" );

addFile( $filename, $filetype = "", $cid = "", $disposition = "" )

Adds the file $filename as attachment to the mail-object. The file will be encoded as base64. At the moment there is no automatic filetype-detection, you have to specify the filetype manually with the $filetype-parameter. If this parameter is left empty, the this method tries to figure out the filetype by using the file-suffix.

The following suffixes are recognized:

gif	GIF-images
jpg	Jpeg-images
png	PNG-images
pdf	PDF-socuments
ps	Postscript-files
exe	Win-/DOS-executable
txt	Text-files
html	HTML-files
htm	HTML-files
mp3	MP3-files
ra	RealAudio-files

If no suffix is recognized, the resulting filetype defaults to "application/octet-stream".

You can also specify a "Content-ID" with the $cid-parameter. This gives you the opportunity to reference this file in the HTML-part of your MIME-mail.

The $disposition-parameter describes the "Content-Disposition" of the attachment. If left empty and if the $cid-parameter is set, then the "Content-Disposition" will be set to "inline". Some mail-clients will display the attached file in the mail-body. If you do not want the attachment to be displayed "inline", you can set the $disposition-parameter to "attachment". If both parameters are ommitted, then the "Content-Disposition" is set to "attachment".

Returns true on success, false otherwise. You can check the error with getErrorCode and getErrorMsg.

See also: addAttachment, setHTMLPart

Example:

include( "mime_mail.class.php" );
$mime = new MIME_Mail;

$file = "/home/marcus/images/pussycat.jpg";
$type = "image/jpeg";

$mime->addFile( $file, $type );

addHeader( $head )

Adds an additional Header to the mail-object. The complete header must be given in the $head-parameter.

See also: addXHeader

Example:

include( "mime_mail.class.php" );
$mime = new MIME_Mail;

$head = "X-Mailer: Microsoft Outlook, Build 10.0.2616";
$mime->addHeader( $head );

addTo( $to_email, $to_name = "" )

Adds a new recipient to the mail-object. $to_email specifies the email-address of the recipient, $to_email specifies the name of the recipient.

See also: addCc, addBcc

Example:

include( "mime_mail.class.php" );
$mime = new MIME_Mail;

$mime->addTc( "doe@domain.com", "John Doe" );
$mime->addTc( "jane.doe@domain.org" );

addXHeader( $key, $val )

Adds an additional extra-header from the given key-value-pair. The key will be extended with a leading "X-".

See also: addHeader

Example:

include( "mime_mail.class.php" );
$mime = new MIME_Mail;

$key = "Mailer";
$val = "Microsoft Outlook, Build 10.0.2616";

$mime->addXHeader( $key, $val );
// will result in:
// "X-Mailer: Microsoft Outlook, Build 10.0.2616"

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

Returns an error-code, if sending the mail results in an error or adding an attachment failed. The error-code is a combination of the following values:

1 - no sender-address specified
2 - no recipient-address specified
4 - no message-body
8 - one or more of the recipient-addresses failed the email-check
16 - one or more of the sender-addresses failed the email-check
32 - attachment-file not found
256 - an error occured in the mail-transport-agent, i.e. outside of the MIME_Mail-class.

See also: getErrorMsg, resetErrorCode

Returns a string describing the error, if an error occured while sending the mail or attaching a file.

See also: getErrorCode, resetErrorCode

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

Initializes all variables of the mail-object. There is no need to call this method directly. All other methods check, if the mail-object is initialized properly and call init if neccessary.
If called directly, all variables, email-addresses and attachments will be reset.

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

quotedPrintable( $string )

Encodes the string $string as a quoted-printable string. For more information about quoted-printable strings see RFC-2045.

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

resetErrorCode()

Resets the error-code. This is useful when adding multiple files and you want to check, if all files were attached correctly.

See also: getErrorCode, getErrorMsg

Example:

include( "mime_mail.class.php" );
$mime = new MIME_Mail;

$file1 = "/home/marcus/pussycat1.jpg";
$okay = $mime->addFile( $file1 );

if( ! $okay ){
    echo $mime->getErrorMsg();
    $mime->resetErrorCode();
}

$file2 = "/home/marcus/pussycat2.jpg";
$okay = $mime->addFile( $file2 );

if( ! $okay ){
    echo $mime->getErrorMsg();
    $mime->resetErrorCode();
}

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

After you have set up all properties of your mail-object, you have to call sendMail to actually send the mail. If sending fails, sendMail returns false. In this case you can check the error with getErrorCode and getErrorMsg. If everything works wll sendMail returns true.

See also: getErrorCode, getErrorMsg

setEnvelop( $env )

Sets the sender-envelop of the mail-object (ie. the fifth-argument of the PHP mail-command). This is the same as giving sendmail the -f commandline-option.

Example:

include( "mime_mail.class.php" );
$mime = new MIME_Mail;

$from_e = "john.doe@domain.com";
$from_n = "John Doe";
$to_e = "jane.doe@domain.com";
$to_n = "Jane Doe";
$env = "info@domain.com";
$text = "Hi there!";

$mime->addTo( $to_e, $to_n );
$mime->setFrom( $from_e, $from_n );
$mime->setEnvelop( $env );
$mime->setPlainPart( $text );
$mime->sendMail();

setFrom( $from_email, $from_name = "" )

Sets the email-address and the name of the sender.

See also: setReplyto, addTo

setHTMLPart( $html )

Set the HTML-part of the multipart-message. If you don't set the HTML-part, no HTML-message will be generated. If you do set the HTML-part, you can also refer to attached images in the mail using the "Content-ID". The "Content-ID" is used by some mailclients to display the attached images in the HTML-body (i.e. you can see images independend of being online or not), rather to access images over the network by using conventional HTTP-URLs (i.e. you must be online to see the images). The HTML-part $html will be encoded as "quoted-printable".

See also: addAttachment, addFile

Example:

include( "mime_mail.class.php" );
$mime = new MIME_Mail;

$from_e = "john.doe@domain.com";
$from_n = "John Doe";

$to_e = "jane.doe@domain.com";
$to_n = "Jane Doe";

$text = "Hi there!";

$html .= "<html>";
$html .= "<body>";
$html .= "<H1>Hi there!</H1>";
$html .= "<img src='cid:mypicture'>";
$html .= "</body>";
$html .= "</html>";

$file = "/home/marcus/images/pussycat.jpg";
$type = "image/jpeg";

$mime->addTo( $to_e, $to_n );
$mime->setFrom( $from_e, $from_n );

$mime->setPlainPart( $text );
$mime->setHTMLPart( $html );

$mime->addFile( $file, $type, "mypicture" );

$mime->sendMail();

setMSPriority( $prio )

Adds a priority-header in Microsoft-Outlook style to the mail-object (i.e. "X-MSMail-priority: High"). The resulting header depends on the $prio-parameter:

1 - High
2 - Medium
3 - Normal
4 - Low

setPlainPart( $plain )

Sets the plaintext-part of the mail-object. If an HTML-part is given with setHTMLPart, the plaintext-part will be the alternative view of the HTML-part. If no HTML-part is given, the plaintext-part will become the conventional mail-body. The paintext-part $plain will be encoded as "quoted-printable".

See also: setHTMLPart

setPriority( $prio )

Adds a generic priority-header to the mail-object (i.e. "X-Priority: 1 (Highest)"). The resulting header depends on the $prio-parameter:

1 - High
2 - Medium
3 - Normal
4 - Low

setReceiverCheckOn( $on = true )

Turn the checks for receiver-addresses on or off. By default all checks are disabled. If turned on, all receiver-addresses (i.e. all addresses in the To-, CC- and BCC-fields) will be checked for correct spelling and a present MX-record.

See also: setSenderCheckOn, setWWWCheckOn

setReplyto( $rpl_email, $rpl_name = "" )

Sets the replyto-address of the sender.

See also: setFrom, addTo, setEnvelop

setSenderCheckOn( $on = true )

Turn the checks for sender-addresses on or off. By default all checks are disabled. If turned on, all sender-addresses (i.e. all addresses in the From-, Replyto- and the Envelop-fields) will be checked for correct spelling and a present MX-record.

See also: setReceiverCheckOn, setWWWCheckOn

setShortlinesOn( $on = true )

Toggles usage of shortlines on or off. When adding files via addFile, the lines of the encoded file will be broken after 76 characters. By default this feature is disabled due to performance reasons.

setSubject( $subj )

Sets the subject of the mail-object.

setWWWCheckOn( $on = true )

Turn checks for WWW-addresses on or off. From my own experience a significant part of people using the internet still believe that his or her email-address is "www.john-doe@domain.com". If you also have users of that kind, turn this check on. It may save you a lot of bouncing error-mails.

This check takes effect only when setSenderCheckOn or setReceiverCheckOn is set. By default the WWW-check is disabled.

See also: setSenderCheckOn, setReceiverCheckOn