Nomad MIME Mail 1.6 - Documentation.

Copyright (C) 2003 - 2008 Alejandro García González.
Oficial Web site: http://www.developarts.com/nomad_mimemail
Support Web site: http://www.phpclasses.org/browse/package/1267.html
Email: nexus at developarts dot com

1. Description.
2. Quick Reference.
3. Function Reference.
4. Change Log.
5. To Do List.
6. Collaborators.
7. License.

1. Description.

Nomad MIME Mail (formerly known as Nexus MIME Mail), is a class for handling and sending mail MIME type, with support for the dispatch by SMTP and SMTP Auth

Currently, this class supports:

Plain Text
HTML
Plain Text with Attachments
HTML with Attachments
HTML with Embedded Images
HTML with Attachments and Embedded Images

It also supports multiple e-mail addresses for sending (to), with a copy (cc) and with a blind carbon copy (bcc), as well as several images embedded in HTML and various attachments

2. Quick Reference.

Attached to this class and documentation is a file called 'nomad_mimemail.test.php' where is a script with an example of sending mail with text, HTML, Image and Deputy Embedded sent via SMTP. .

To use MIME Mail Nomad is necessary to declare the object as follows:

include ('nomad_mimemail.inc.php');
$mimemail = new nomad_mimemail();

Plaintext

Normally this is how the function 'mail ()' would operate. PHP, however in this version is created so a little different because it sent the body of the message headers and MIME type

$mimemail->set_from("me@mail.com");
$mimemail->set_to("friend@mail.com");
$mimemail->set_subject("Nomad MIME Mail: Plain Text");
$mimemail->set_text("This is a MIME Mail with:\n\n- Plain Text");

if ($mimemail->send()){
echo "The MIME Mail has been sent";
}
else {
echo "An error has occurred, mail was not sent";
}

Text and HTML

Example of sending mail with text and HTML

$mimemail->set_from("me@mail.com");
$mimemail->set_to("friend@mail.com");
$mimemail->set_subject("Nomad MIME Mail: Plain Text + HTML");
$mimemail->set_text("This is a MIME Mail with:\n\n- Plain Text\n- HTML");
$mimemail->set_html("<HTML><HEAD></HEAD><BODY>This is a MIME Mail with: - Plain Text- HTML</BODY></HTML>");

if ($mimemail->send()){
echo "The MIME Mail has been sent";
}
else {
echo "An error has occurred, mail was not sent";
}

Plaintext with Attachments

Example of creating an email with an attachment and Plain Text. You can do more than adding attachments with the 'add_attachment' method. For more information, check the function reference guide.

$mimemail->set_from("me@mail.com");
$mimemail->set_to("friend@mail.com");
$mimemail->set_subject("Nomad MIME Mail: Plain Text + Attachment");
$mimemail->set_text("This is a MIME Mail with:\n\n- Plain Text\n- Attachment");
$mimemail->add_attachment("test_attachment.tar.gz", "file.tar.gz");

if ($mimemail->send()){
echo "The MIME Mail has been sent";
}
else {
echo "An error has occurred, mail was not sent";
}

Plain Text and HTML with Attachments

Example to create an email with Plain Text, HTML and a deputy. You can add more than one attachment using the 'add_attachment'.

$mimemail->set_from("me@mail.com");
$mimemail->set_to("friend@mail.com");
$mimemail->set_subject("Nomad MIME Mail: Plain Text + HTML + Attachment");
$mimemail->set_text("This is a MIME Mail with:\n\n- Plain Text\n- HTML\n- Attachment");
$mimemail->set_html("<HTML><HEAD></HEAD><BODY>This is a MIME Mail with: - Plain Text- HTML- Attachment</BODY></HTML>");
$mimemail->add_attachment("test_attachment.tar.gz", "file.tar.gz");

if ($mimemail->send()){
echo "The MIME Mail has been sent";
}
else {
echo "An error has occurred, mail was not sent";
}

Plain Text and HTML with Embedded Images

Example of creating an email with HTML, plain text and an Embedded Image. For the image embedded function, the attachment must have the same name as indicated on the tag 'IMG' HTML message.

$mimemail->set_from("me@mail.com");
$mimemail->set_to("friend@mail.com");
$mimemail->set_subject("Nomad MIME Mail: Plain Text + HTML + Embedded Image");
$mimemail->set_text("This is a MIME Mail with:\n\n- Plain Text\n- HTML\n- Embedded Image");
$mimemail->set_html("<HTML><HEAD></HEAD><BODY>This is a MIME Mail with: - Plain Text- HTML- Embedded Image<img src='image.gif' border='0'></BODY></HTML>");
$mimemail->add_attachment("test_image.gif", "image.gif");

if ($mimemail->send()){
echo "The MIME Mail has been sent";
}
else {
echo "An error has occurred, mail was not sent";
}

Plain Text and HTML with Embedded Image and Attachments

Example of creating an email with HTML, plain text, an embedded image and an attachment. For the embedded image to work, the attachment archive must have the same name as indicated on the tag 'IMG'

$mimemail->set_from("me@mail.com");
$mimemail->set_to("friend@mail.com");
$mimemail->set_subject("Nomad MIME Mail: Plain Text + HTML + Embedded Image + Attachment");
$mimemail->set_text("This is a MIME Mail with:\n\n- Plain Text\n- HTML\n- Embedded Image\n- Attachment");
$mimemail->set_html("<HTML><HEAD></HEAD><BODY>This is a MIME Mail with: - Plain Text- HTML- Embedded Image- Attachment<img src='image.gif' border='0'></BODY></HTML>");
$mimemail->add_attachment("test_image", "image.gif");
$mimemail->add_attachment("test_attachment.tar.gz", "file.tar.gz");

if ($mimemail->send()){
echo "The MIME Mail has been sent";
}
else {
echo "An error has occurred, mail was not sent";
}

Sending Authenticated SMTP

To send mail via SMTP it is necessary to call the 'set_smtp_host' method and to send mail using SMTP authentication it is necessary to use the 'set_smtp_auth' method.

$mimemail->set_from("me@mail.com");
$mimemail->set_to("friend@mail.com");
$mimemail->set_subject("Nomad MIME Mail: HTML + Auth SMTP");
$mimemail->set_html("<HTML><HEAD></HEAD><BODY>This is a MIME Mail with: - Plain Text- HTML</BODY></HTML>");

$mimemail->set_smtp_host("domain.com");
$mimemail->set_smtp_auth("user", "pass");

if ($mimemail->send()){
echo "The MIME Mail has been sent";
}
else {
echo "An error has occurred, mail was not sent";
}

At the moment this version is in testing and would appreciate any assistance possible to support such a large amount of SMTP's. If you have a mistake is possible to review the entire conversation that makes this script with SMTP. to do so before the 'send' call to the function 'set_smtp_log' a true, and the verdict can bring everything through 'get_smtp_log' as illustrated below:

$mimemail->set_smtp_log(true);

if ($mimemail->send()){
echo "The MIME Mail has been sent";
}
else {
echo $mimemail->get_smtp_log();
}

If so, I ask you to leave your report in The Forum where this kind of try to adapt as much as possible the response received from SMTP.

3. Function Reference.

add_attachment	Add an attachment.
add_bcc	Adds a carbon copy mail with hidden recepient/td>
add_cc	Adds a mail with carbon copy
add_content_attachment	add an attachment to send the content directly
add_reply_to	Adds an email response
add_to	Add a mail destination
get_eml	Get EML format mail
get_smtp_log	Get the SMTP log
get_version	Returns the installed version of this class
new_mail	Create a new mail
nomad_mimemail	Constructor
send	Send Mime Mail
set_bcc	Establishes a carbon copy with hidden recepient
set_charset	Set the character set to be used in the email.
set_cc	Set a carbon copy recepient
set_from	Set the From Address
set_html	Set the HTML content of the message
set_reply_to	Set the Reply To address
set_return_path	Establish the return path
set_smtp_auth	Set the Username and Password to use for SMTP Auth connections
set_smtp_host	Set the SMTP host
set_smtp_log	Set the SMTP Log on or off.
set_subject	Set the subject line contents
set_text	Set the plain text contents of an email.
set_to	Set the destination address.

add_attachment

bool add_attachment(string file, string name, [string type])

Description:

Add an attachment to an e-mail

The 'file' parameter should provide the fully qualified location (path and name) of the file you want to attach. This method opens the file with fopen.

When you send a file via a POST method, PHP initializes a variable superglobal with information that can be used directly by this method. For example:

$_FILES['userfile']['name'] is the original name of the file
$_FILES['userfile']['type'] is the mimetype of the file as provided by the browser.
$_FILES['userfile']['tmp_name'] is the location of the temporary file stored on the server.

In the particular case of needing to embed an image inside a post, it is necessary to create the "Tag" in the corresponding HTML message with the correct reference to the "name" of the image file and its link "src". For more information you can review the examples that come with this class.

Parameters:

file

Location of the file you want to attach

name

Name which of the file to send

type

MIME type of file you want to attach

Examples:

$mimemail->add_attachment($_FILES['userfile']['tmp_name'], $_FILES['userfile']['name'], $_FILES['userfile']['type']);
$mimemail->add_attachment('img/image_test.gif', 'myimage.gif');

add_bcc

bool add_bcc(string mail_bcc, [string name])

Description:

Add a syntactically correct email address as a hidden carbon copy to an existing list of addresses. Returns 'true' if it is added successfully or 'false' otherwise. You can optionally specify a contact name.

Parameters:

mail_bcc

Recipient's Email Address

name

Name of contact or text

Examples:

$mimemail->add_bcc('foo@mail.com', 'Mr. Foo');
$mimemail->add_bcc('bar@mail.com', 'Mr. Bar');

add_cc

bool add_cc(string mail_cc, [string name])

Description:

Add a syntactically correct email address as a carbon copy to an existing list of addresses. Returns 'true' if it is added successfully or 'false' otherwise. You can optionally specify a contact name.

Parameters:

mail_cc

Destination Address

name

Name of contact or text

Examples:

$mimemail->add_cc('foo@mail.com', 'Mr. Foo');
$mimemail->add_cc('bar@mail.com', 'Mr. Bar');

add_content_attachment

bool add_content_attachment(string content, string name, [string type])

Description:

Add an attachment to e-mail directly from the content. This feature is especially useful when content is generated directly in code, such as xml files, pdf, pictures, etc.. you want to attach.

In the parameter 'content' is due to pass the content directly. Unlike 'add_attachment' in this method will not open any external file, since the content is passed directly.

In the particular case of needing embed an image inside a post, it is necessary to create the "Tag" in the corresponding HTML message with the correct reference to the "name" of the image file and its link "src". For more information you can review the examples that come to this class.

Parameters:

content

Content to attach file as

name

Name of the file sent.

type

Mime type of the file sent.

Examples:

$mimemail->add_content_attachment("This is the content of text file", "textfile.txt");

add_reply_to

bool add_reply_to(string mail_reply_to, [string name])

Description:

Add an email address at which you prefer to receive a reply.

Parameters:

mail_reply_to

Email address to receive responses.

name

Name of contact or text

Examples:

$mimemail->add_reply_to('foo@mail.com', 'Mr. Foo');
$mimemail->add_reply_to('bar@mail.com', 'Mr. Bar');

add_to

bool add_to(string mail_to, [string name])

Description:

Add an email address for the existing ones, which must be syntactically correct by returning 'true' if it is added successfully or 'false' otherwise. You can optionally specify a contact name.

Parameters:

mail_to

email address of recipent

name

Name of contact or text

Examples:

$mimemail->add_to('foo@mail.com', 'Mr. Foo');
$mimemail->add_to('bar@mail.com', 'Mr. Bar');

get_eml

string get_eml()

Description:

Return the content of mail formed in EML format that can be used to file in a database or text files.

Parameters:

There are no parameters.

Examples:

$correo_eml = $mimemail->get_eml();

get_smtp_log

string get_smtp_log()

Description:

Return the content of the conversation between this class and SMTP.

To use this feature is necessary to advance the property 'set_smtp_log' to 'true'. This is especially useful when you have a problem with the shipment by SMTP and want to review all the commands sent and the responses of the SMTP server.

Parameters:

There are no parameters.

Examples:

$mimemail->set_smtp_log(true);

if ($mimemail->send()){
echo "The MIME Mail has been sent";
}
else {
echo $mimemail->get_smtp_log();
}

get_version

string get_version()

Description:

Return the installed version of this class.

Parameters:

There are no parameters.

Examples:

echo "Nomad MIME Mail, version: " . $mimemail->get_version();

new_mail

void new_mail([string from], [string to], [string subject], [string text], [string html])

Description:

This feature is a quick way to erase all the variables created by a former mailing on the same subject and / or to assign them quickly some of the options for sending an e-mail MIME

All Parameters are optional.

Parameters:

from

Senders email address

Destination email address

subject

Subject of the message

text

Plain Text message content

html

HTML message content

Examples:"

$from = "me@mail.com";
$to = "friend@mail.com";
$subject = "Hello friend";
$text = "This is my Text Plain Message";
$html = "This is mi message in HTML";

$mimemail->new_mail($from, $to, $subject, $text, $html);

nomad_mimemail

void nomad_mimemail()

Description:

This is the class constructor

Parameters:

There are no parameters.

Examples:

$mimemail = new nomad_mimemail();

send

bool send()

Description:

Send mail MIME with features added in the composition of the message.

If the shipment has been successfully returns' true 'if' false '

Parameters:

There are no parameters.

Examples:

if ($mimemail->send()){
echo "The MIME Mail has been sent";
}
else {
echo "An error has occurred, mail was not sent";
}

set_bcc

bool set_bcc(string mail_bcc, [string name])

Description:

Establishing an e-mail address as a carbon copy hidden 'bcc', which must be syntactically correct by returning 'true', otherwise it returns' false '. You can optionally specify a contact name.

Note: This method removes any postal mail or previously existing in the variable 'mail_bcc'

Parameters:

mail_bcc

A valid destination email address or list of addresses.

name

Contact name or text.

Examples:

$mimemail->set_bcc('jhon@mail.com', 'Mr. Doe');

set_charset

void set_charset(string charset)

Description:

Sets the character set that will be used to generate the e-mail.

Parameters:

charset

A valid character set

Examples:

$mimemail->set_charset("ISO-8859-1");

set_cc

bool set_cc(string mail_cc, [string name])

Description:

Establishing an e-mail address as a carbon copy 'cc', which must be syntactically correct by returning 'true', otherwise it returns' false '. You can optionally specify a contact name

Note: This method removes any postal mail or previously existing in the variable 'mail_cc'

Parameters:

mail_cc

A valid destination email address.

name

Name or text for contact

Examples:

$mimemail->set_cc('jhon@mail.com', 'Mr. Doe');

set_from

void set_from(string mail_from, [string name])

Description:

Establece la dirección de correo del remitente, el cual debe ser sintácticamente correcto. Opcionalmente se puede especificar un nombre de contacto

Parameters:

mail_from

Valid originating email address.

name

Name or text describing contact.

Examples:

$mimemail->set_from('fake@mail.com', 'No Reply');

set_html

void set_html(string html)

Description:

Set the HTML message content

Parameters:

html

HTML message content

Examples:

$mimemail->set_html('This is mi message in HTML');

set_reply_to

bool set_reply_to(string mail_reply_to, [string name])

Description:

Set the sender's email address, which must be syntactically correct. You can optionally specify a contact name.

Parameters:

mail_reply_to

Reply address

name

Name or contact text

Examples:

$mimemail->set_reply_to('me@mail.com', 'Your Nightmare');

set_return_path

bool set_return_path(string mail_return_path)

Description:

It sets the direction of the return mail, on many occasions is used to indicate that mail will be sent in case of error or in the absence of a mail destination.

Parameters:

mail_return_path

A valid return email address

Examples:

$mimemail->set_return_path('hostmaster@mail.com');

set_smtp_auth

bool set_smtp_auth(string user, string pass)

Description:

Set the username and password required by the SMTP server. For this method to work, you must call 'set_smtp_host', which declares it is the host that has the SMTP to use.

It is only necessary to call this method when required to use SMTP authentication.

Parameters:

user

Username for SMTP authentication, in many cases, the username is the account holders email address.

pass

SMTP server password.

Examples:

$mimemail->set_smtp_host("domain.com");
$mimemail->set_smtp_auth("user", "pass");

if ($mimemail->send()){
echo "The MIME Mail has been sent";
}
else {
echo "An error has occurred, mail was not sent";
}

set_smtp_host

bool set_smtp_host(string host, [int port])

Description:

It establishes where the host will be connected by SMTP for sending mail. Call this method automatically establishes that the mail will be sent via SMTP.

In the event of did not need to send the mail via SMTP, it is not necessary to call this method, and let the mail be sent by the 'mail' PHP.

If you require SMTP authentication, you must also call the function 'set_smtp_auth'

Parameters:

host

The domain name or IP address to which this class will be connected to send mail.

port

Optionally you can declare a port to connect to the server, the default port is set at 25.

Examples:

set_smtp_log

void set_smtp_log(bool log)

Description:

Provides that save the entire conversation between this class and an SMTP, which can then be retrieved via the 'get_smtp_log'. This is especially useful when you have a problem with the shipment by SMTP and want to review all the commands sent and the responses of the SMTP server.

Parameters:

log

If you want to retrieve the SMTP conversation with the state to true. It is found in default 'false'.

Examples:

$mimemail->set_smtp_log(true);

if ($mimemail->send()){
echo "The MIME Mail has been sent";
}
else {
echo $mimemail->get_smtp_log();
}

set_subject

bool set_subject(string subject)

Description:

Set the email subject line content

Parameters:

subject

The message subject in text form.

Examples:

$mimemail->set_subject('Contact mail from my page');

set_text

void set_text(string text)

Description:

Set the plain text message content

Parameters:

text

Message in plain text

Examples:

$mimemail->set_text('This is mi message in plain text');

set_to

bool set_to(string mail_to, [string name])

Description:

Establishing an email destination, which must be syntactically correct and returns' true ', otherwise it returns' false'. You can optionally specify a contact name.

Note: This method removes any postal mail or previously existing in the variable 'mail_to'.

Parameters:

mail_to

A correctly formed destination address

name

Name or contact text

Examples:

$mimemail->set_to('jhon@mail.com', 'Mr. Doe');

4. Change Log

Version 1.0

Version published in phpclasses.org. Written entirely in Spanish.

Version 1.2

Class translated into English and Spanish version discarded.
Created Spanish language documentation
Variable charset
Fixed a bug which prevented repetetion of a single image used multiple times in HTML content.
Support for Windows long file names in attachments

Version 1.3

Support for 'Return Path'
Support for background images
Support for embedded CSS
Support for reply mail
Added get_eml method
Significant corrections to code syntax
Optimized search for embedded images
Corrected some bugs

Version 1.4

Changed name from "Nexus MIME Mail" to "Nomad MIME Mail"
Support for adding content as content attachment 'add_content_attachment'
Support for more than one email response 'add_reply_to'
Support for sending via SMTP 'set_smtp_host'
Support for sending via SMTP authenticated 'set_smtp_auth'
Support for debugging the conversation between the script and the SMTP server using 'set_smtp_log' and 'get_smtp_log'
Code documented in Doxygen style
Correction of some bugs
Documentation Update

Version 1.5

Fixed "UNDISCLOSED Recipients" error
Fixed syntax error "_build_headers"
Fixed charset problems in plain text component of "_build_body"
Added the method "set_charset ()"
New logo and project page
Actualización de la documentación

Version 1.6

Changed library headers.
Fixed problem of line breaks in Qmail
Changing style comments to phpDocumentor
Fixed problem with _php_version_check ()
Fixed problem with the Post Duplicates
Documentation Update
New English Documentation (TNX to David M. Graham)

5. To be done.

Check that to, cc and bcc fields are not repeated in e-mails.
Build a more sophisticated HTML to plain text parser.
Avoid duplicate use of the same names in attachements.

6. Colaborators.

We thank those who have given their support and support for the development of this class.

7. License.

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

8. Copyright.

This translation was prepared by David M. Graham of the osCommerce University Press using texts provided by the Nomad Mime Mail site. Thus far minimal adjustments have been made to the grammar only. Such copyrights as might accrue to this process are granted solely to Alejandro García González.

The osCommerce University Press

Nomad MIME Mail 1.6 - Documentation.

Table of Contents

1. Description.

2. Quick Reference.

3. Function Reference.

add_attachment

add_bcc

add_cc

add_content_attachment

add_reply_to

add_to

get_eml

get_smtp_log

get_version

new_mail

nomad_mimemail

send

set_bcc

set_charset

set_cc

set_from

set_html

set_reply_to

set_return_path

set_smtp_auth

set_smtp_host

set_smtp_log

set_subject

set_text

set_to

4. Change Log

5. To be done.

6. Colaborators.

7. License.

8. Copyright.