h2. OireMail, version 2.4.1
Welcome to OireMail, a class designed to send e-mail through a custom SMTP server defined in the class properties.
h3. Features and overview
This class can send mail through the SMTP server defined in the properties (see below), with authentication or not. For a while it isn't able to send attachments (this is planned for further releases of version 2). However, the headers are properly formed and multiple messages are send in one queue so the process is much quicker than with the built-in @mail()@ PHP function.
the class itself, as well as this documentation file, is written in the UTF-8 encoding, and the mail is sent in this encoding, also. We hope that it will become a standard for everyone some day.
Since the properties are defined in the constructor of the class, you might want to create an auxiliary class extending OireMail to set the values for the properties (see the _examples.php_ file). If you plan to use the class once or to have different values for the properties each time you use the class, just set them as properties of the newly created object (see the same example file).
_Note_: since version 2.0.0, the class doesn't stop your script from working, nor does the @send()@ method return an error if the sending was not successful. The class generates an exception instead, so consider using a @try...catch@ block (see _examples.php_).
_Note_: since version 2.3 the class is called @Mail@ and belongs to the namespace @Oire@. So please update your code to use @\Oire\Mail@ instead of just @OireMail@ (see _examples.php_).
The following is required for OireMail to work correctly:
* Php 5.3 or higher;
* A correctly set up SMTP server or ability to send mail via public SMTP servers;
* The "Iconv":http://php.net/manual/en/book.iconv.php library for headers encoding.
h3. Class properties
* @$from_name@ â€” the name of the sender (such as _John G. Doe_). It may be left empty, the class will handle this properly.
* @$from_addr@ â€” the e-mail address of the sender (such as firstname.lastname@example.org_).
* @$smtp_server@ â€” the server sending the mail (such as _smtp.yourdomain.com_).
* @$smtp_data@ â€” the array of SMTP parameters. This is needed only if sending with authentication. For now you should give to the keys names indicated below, a simple zero-indexed array won't work.
** @domain@ â€” SMTP domain (such as _yourdomain.com_). Since the domain might be a different part of the actual server name, you should set this in the property.
** @login@ â€” the login for the account which sends the mail (such as email@example.com_ or just _john_ for some servers).
** @pass@ â€” the password for the account sending the mail.
* @$smtp_port@ â€” the port used by the SMTP server. By default it is set to 25;
* @$debug@ â€” whether exception messages should be verbose or not. For instance, if there is a names/addresses mismatch, the class outputs both names and e-mails arrays if this is set to true. By default @$debug@ is set to false.
h3. The @Send()@ method and its parameters
The main method used for sending mail is @Send()@. It takes the following parameters:
* array/string @$tonames@ â€” the names of the recipients. If there is only one name, it may be a string, otherwise it should be an array.
* array/string @$toemails@ â€” the addresses of the recipients. If there's only one address, it may be a string, otherwise it should be an array.
*Note*: there shouldn't be any names/mails mismatch, or you'll get an exception. If you have, for example, three names and five addresses, just set all of the items leaving some of them as "", e.g.:
bc. $names=array("John G. Doe", "", "", "Mary R. Smith", "Harry J. Roe");
* string @$subject@ â€” The subject of the message.
* string @$plaintext_message@ â€” The body of the message.
* Bool/array @$is_html@ â€” Whether to send messages in HTML or not.
*Note*: you should provide exactly the same number of booleans as the number of items in the @toemails@ array. Alternatively, you can provide one boolean, which means that all of the recipients should or should not recieve an HTML message.
* @$html_message@ â€” If you have any @true@ values in the previous parameter, you should provide a well-formed HTML message. If you don't provide any, then a plain text message will be send, except that it will have a doctype of HTML 5, subject as title and a heading below the body, and line breaks will be converted to @<br>@'s.
p. The @Send()@ method returns no value. If an error has occured during the sending process, an exception will be thrown. You can easily catch it using the @try...catch@ block, and thus avoid your script from dying at an e-mail error.
h3. Versioning and changelog
We use standard major.minor.patch versioning system.
* Version 2.4.1: Added an @debug@ example.
* Version 2.4.0:
** Fixed a namespace error when exceptions were thrown;
** Added the @debug@ property.
* Version 2.3.1:
** Added "Composer":http://getcomposer.org/ support;
** Added "Travis CI":http://travis-ci.org/ support.
* Version 2.3:
** the class is now namespaced and thus called @\Oire\Mail@;
** The documentation is converted to Textile which is easier to maintain, instead of Markdown;
** We started using "Git flow AVH edition":https://github.com/petervanderdoes/gitflow for our repository which is much more comfortable in branching and maintaining the code;
** Added a new @makeHTML@ private method to better prepare an HTML message if not provided separately;
** The code is now properly indented.
* Version 2.2.1:
** Fixed unnecessary headers folding causing errors when replying to a message send by OireMail;
** The readme is properly marked up using Markdown.
* Version 2.2.0:
** The repository was permanently moved to Github;
** Now PHP 5.3 or higher is required;
** We're removed unnecessary @HeaderEncode()@ private method. Now using @iconv_mime_encode()@ instead, so the _Iconv_ library is required;
** Docs: Now only English documentation is maintained;
** Fixed minor bugs.
* Version 2.1.0:
** Added ability to send HTML messages: provide @$is_html@ array of booleans for each recipient, and @$html_message@ for the message to be sent;
** Now all the SMTP authentication related data is consolidated into one single @$smtp_data@ array (see the manual for details);
** If there are empty addresses in the @$toemails@ array, now they are removed before sending mail along with the corresponding entries in the @$tonames@ array, and you won't get exceptions in that case.
* Version 2.0.0:
** The @Send()@ method returns nothing, implemented PHP exceptions instead;
** Some tweaks to the documentation.
* Version 1.4.3:
** Replaced short opening tag to the long one to fit the newest PHP conventions;
** Fixed the message id so it would display _@OireMail_ if no @smtp_domain@ is specified;
** Created a Mercurial repository at Bitbucket;
** Docs: added a heading with the version number, so it would be easy to track changes;
** Docs: Added a note about the Mercurial repository.
* Version 1.4.2: Fixed the format of the _Return-Path_ header.
* Version 1.4.1:
** At last fixed a bug where the date would return in UTC timezone, now it is correct;
** Trying to override the _Return-Path_ header for preventing errors and marking mail as possible spam when this header is formed by the SMTP server itself.
* Version 1.4: Implemented a possibility to choose whether to use authentication to send mail or not.
* Version 1.3.1:
** Corrected the @$smtp_port@ property, now it's really set to 25 by default;
** Structured the changelog section so it is easier to read and navigate.
* Version 1.3:
** Minor optimization of the main code;
** Added the @$smtp_port@ property;
** Corrected the _examples.php_ file;
** Added the Russian documentation.
* Version 1.2: Changed the properties initialization method â€” now they are defined in the class constructor.
* Version 1.1.5: a bug was fixed where the _From:_ header was not properly UTF-8 encoded.
* Version 1.1: Introduced two alternative methods of quoted-printable encoding depending on the PHP version.
* Version 1.0: the first release of the class.
The idea and some concepts and excerts of code (such as the @getResponse()@ private method) are inspired by or gotten from "this article":http://www.php.su/articles/?cat=email&page=007 (in Russian).
Â© NostiÃ« & Menelion ElensÃºlÃ«, "The Magical Kingdom of OirÃ«":http://oire.me/, 2010 â€” 2013