Docstoc

email system documentation

Document Sample
email system documentation Powered By Docstoc
					                               Email System Documentation

First of all thanks for buying the Email System. This documentation will guide you so you will have this
email system set up in no time.

So what have I bought?
Ok so first of all let me explain what you have actually purchased because some of you might be
wondering.

This is a fully functioning PHP Email Class, this will allow you to send emails with or without attachments in
no time at all by integrating it into your current projects. As a demonstration I have also included a simple
yet powerful application that allows you to see that functionality.

So i'm guessing you like the script and you want me to shut up and show you how to set it up? Just so this
documentation is easy on those less experienced programmers I am going to assume you know very little
about php so please don't be offended.

How do I set this thing up?
Ok setting up is a piece of cake... I am first going to show you how you could integrate this into a current
script.

<?php
require_once('path/to/class/JCEmail.class.php');
$Email = new JCEmail();
?>

Ok so what we have done here is required our class and instantiated (Posh word for created an object) our
class. This means we can access all of the goodness it has to offer. Wanna know the best part? You don't
need to know squat about php to use it.

How to send an email.
Ready, this is how to send the basic of basic email but you will see how easy it is to use the class.

<?php
$Email->set_to('to@suburbanarctic.com');
$Email->set_from('from@suburbanarctic.com');
$Email->set_subject('This is the subject!');
$Email->set_message('This is the message!');
$Email->send_email();
?>

Some of you maybe thinking wow! Just that to send an email? And others maybe thinking urm... i'm
scared. Well don't be literally copy and paste them 7 lines of code in a script and save it as test.php and
check your inbox. But of course we don't want to do this every time we send emails. (We will learn about
integration later.)

How do I add HTML functionality?
Ok so you want to be able to send HTML formatted emails? No problem add this to your code above.

$Email->set_html();

Ok so adding that one line of code has now extended the ability of our email system. You can now go a
head and add HTML into your script like so.

$Email->set_message('
<h1>Hello, World!</h1>
<p>This is an awesome script!</p>
');

You can add this in anywhere before the send_email() method. And yes for those wondering, you can add
inline styling to format your emails to how you like. So if you have been following this guide your code
should look like this;

$Email->set_to('to@suburbanarctic.com');
$Email->set_from('from@suburbanarctic.com');
$Email->set_subject('This is the subject!');
$Email->set_message('This is the message!');
$Email->set_html();
$Email->send_email();

We can also add BCC's and CC's (Blind Carbon Copy, Carbon Copy) first of all some of you may not know
what that means so lets give a brief description.

BCC – Blind Carbon Copy, basically means you can add people into the email but no one will know anyone
else has been added in. So when you send someone and email you can send it to multiple people but
neither one will know. (If that makes sense)

CC – This means you can add multiple people into the email and they will know who has been added into
the email. So you can send it to multiple people and they will be aware you have sent it to multiple people,
like those chain mails you sometimes get. Grr!

So how do we add these? Adding them is just as easy as the set_email() method we invoked earlier,
however, these require an array (incase we was to add multiple people) let me show you and you will see
what I mean.

Adding BCC
$bcc = array('one@gmail.com','two@gmail.com','three@gmail.com');

Ok see how we have added multiple emails into this array? Well thats the hard part over. If you don't
understand what we have just done don't worry just copy and paste what I do. And if you only need one
just do this;

$bcc = array('one@gmail.com');

Now to add this into our script, remember! Add this anywhere before the send_email() method is invoked.

$Email->add_bcc($bcc);
Ladies and gentlemen that is all we need to do to add multiple people into our email script.

Adding CC
And now to add the CC, you guessed it, it is going to be just as easy pretty much copy and paste what we
have learned above, but just for clarity.

$cc = array('one@gmail.com','two@gmail.com','three@gmail.com');

Pretty much the same, create the array of CC's or if you only need to add one then use the array below.

$cc = array('one@gmail.com');

Now to add this into our script, remember! Add this anywhere before the send_email() method is invoked.

$Email->add_cc($cc);

How about that? You have now learned to send your script to multiple people!
I want to send attachments, so how?
Ok so how do you add attachments to this email script? Now I bet your thinking there is going to be tons
and tons of code and... No (unless you knew cause you glanced below when I mentioned tons of code).

Ok first of all the method I am going to show you assumes the attachment is located in the same directory
of this script. What I mean by that is when you upload this script to your web server the attachment will be
located in the same folder as this script. (JCEmail.class.php)

Ok so we need to create an array of data (again, I know i'm sorry) ok we can send multiple attachments and
I will show you how thats done after. Ok so create a new array and fill it with the information of the file like
so;

$attachment = array( array ( 'file' => '/path/to/file/my_cv.pdf', 'mimetype' =>
'application/pdf', 'filename' => 'my_cv.pdf' ) );

I'm sorry if that seems confusing but let me help you, ok you can see we have an array within side an array
(Multidimensional array) this means we can plonk as many attachments inside this as we want. You can see
we need 3 things and those are file, mimetype, filename.

File – this wants the file or the path to the file. You can see we have put in /path/to/file/my_cy.pdf (if your file
is in the same section as the class then just leave the file name there like my_cv.pdf)

mimetype – Ok this is what is probably confusing you, don't worry though this just wants to know what
kind of file is it. You can look them up here: http://www.ltsw.se/knbase/internet/mime.htp I will list a few.
If you are uploading an...

Image use image/(then extension)jpg
              image/png
              image/gif

Music use audio/mp3
              audio/x-wav

Video use video/mpeg
               video/quicktime
               video/mp4

Hopefully those are some you will use most, but others can be found using the link I supplied. So back to
the piece of code, we have out array made next we need to add it into our script. Just plonk this bit of code
anywhere before the send_email();

$Email->send_attachment($attachment);

And thats it, if the attachment was in the correct location the user will successfully receive it, best of all if
there was an error the email will be sent just in plain text.

How do I change the priority of my emails?
Ok so by default there are allot of things the class provides and this is one of them, so if you don't supply
any mail priority then the default will be 3.

You have the following to choose from:

1 – Highest
3 – Medium
5 – Lowest

$Email->set_priority(1);

Again stick this somewhere before the send_email(); This will then set the email's priority to 1 (the highest).
How do I Validate emails?
Ok the class validates all the emails you insert into it anyway and if they fail they return false meaning the
email sending will fail. But thats more advanced you can enable explanatory outputs from the class but
thats more advanced and many of you wont need to use that.

Validation is simple, you could use this feature if you wanted to add this class to your own project. You can
simple do this.

$Email->validate_email_address('my_email_to_validate@example.com');

This returns true or false so placing it into a simple if/else statement will suffice, see the example below.
If(!$Email->validate_email_address($email))
{
      echo 'I\'m sorry the email you supplied is invalid!';
}
else
{
      echo 'Your email address is valid, thanks!';
}

As you can see its easy as pie to include and use, the class has some more advanced debugging features,
but all above should be more than enough to get you set up. At the time of writing this documentation my
mail server is down so contact me on jonnysnip3r@gmail.com but when my mail server is backup contact
me on john@suburbanarctic.com (Around 7th May 2011) I will be more than happy to assist you.

I want more advanced debugging features!
Ok this is easy to incorporate, you can simple do so by adding the following code (perhaps you may want
to comment out the send_email() function whilst you debug) add the following line of code.

$Email->enable_error_checking();

Ok so we have enabled error checking now, we can now echo out certain method calls, see the class
comments to determine what methods output what. See the example below.

echo $Email->add_cc($cc);

// This will output the following (providing there was an error)
Invalid email address supplied: Email ' . $cc[$i]; // Email causing error.

Hmm, I bet I can't add my own custom headers?
Well you guessed incorrect, you can add your own headers and its just as easy as
everything else I have shown you.

$Email->add_headers('My Custom Header Here...');
$Email->add_headers('and another');
$Email->add_headers('and one more for good luck!');

Ok thats it, that is all the documentation you need to help you be on your way, remember if you need any
assistance use the email above to contact me. The class contains well documented code so try there first
but feel free to email.

The index.php file that contains the upload script is a demonstration of the classes ability but feel free to
modify and use it how you wish!

Once again thanks for buying this class.

				
DOCUMENT INFO
Shared By:
Categories:
Stats:
views:13
posted:8/4/2012
language:simple
pages:4
Description: email system,