interface

Mailer Interface
Basic Code Sample
Howto use mailer class in your own programs

To use the mailer class:-

mailer mail("myspiffyfriend@spiffy.com",       // who the mail is too
            "me@somewhere.net",                // who the mail is from
            "There is always room for FooBar", // subject for the email
            "Foo\nBar",                        // content of the message
            "ns.somewhere.net");               // the nameserver to contact
                                               // to query for an MX record

mail.send( );

To facilitate the class being used with Boost::Threads http://www.Boost.org.
e.g.

#include <boost\thread\thread.hpp>
boost::thread thrd(mail);            // operator( )( ) called implicitly
// thrd.join( );                     // optional

If your not using boost::thread then just call operator( )( ) directly as above or use the send( ) function.
That’s it. If there is an error however. The class members
will not throw an exception or report failure. To find if
the mail was delivered correctly use the response method
of class mailer, e.g.

// A valid response will begin with the string "250"
// see rfc 821 for response codes, section 4.2.2.>
if(mail.response( ).substr(0,3) != "250") {
  // error
}

Alternatively you can use the second constructor for mailer, passing a vector
as the message body. The example below also shows how to send directly
to an SMTP server rather than querying dns for MX records.

std::vector<char> vec;
std::string mess("Foo\nBar");
for(std::string::size_type i = 0; i < mess.length( ); ++i)
  vec.push_back(mess[i]);

jwsmtp::mailer mail("myspiffyfriend@spiffy.com",       // who the mail is too
                    "me@somewhere.net",                // who the mail is from
                    "There is always room for FooBar", // subject for the email
                    vec,                               // content of the message
                    "mail.somewhere.net",              // smtp server to mail to
                    jwsmtp::mailer::SMTP_PORT,         // default smtp port (25)
                    false);                            // do not query MX records
                                                       // directly to mail.somewhere.net

To send to mutiple recipients (to multiple email addresses), construct an object of the mailer class as above. Then call the addrecipient method (before calling mailer::operator( )( ) ) to add email addresses to send the mail to. e.g.

mail.addrecipient("someoneElse@somewhere.net");
// blind carbon copy this next address
mail.addrecipient("whooton@somewhere.net", mailer::Bcc);

The mail will now be sent to to these two addresses aswell as the address
passed in the constructor. To remove a recipient from the recipients list call
the removerecipient method with the exact address
passed into the constructor or the addrecipient methods. e.g.

mail.removerecipient("someoneElse@somewhere.net");

To remove all recipients from the recipients list call
the clearrecipients method. e.g.

mail.clearrecipients( );

After construction the body of the mail & the subject of
the mail can be changed using the setmessage & setsubject
functions respectively. e.g.

mail.setmessage("The new message that will be received");
mail.setsubject("Always room for improvement");

To send a message in HTML format call the setmessage HTML functions:

mail.setmessageHTML(const std::string& newmessage);
mail.setmessageHTML(const std::vector<char>& newmessage);
mail.setmessageHTMLfile(const std::string& filename);

e.g.

string html("<html>"
            "<body>"
            "html message<br /><br />"
            "<b>bold</b><br />"
            "<i>italic</i><br />"
   ... etc
            "</body>"
            "</html>");
mail.setmessageHTML(html);

To add an attachment use the attach function e.g.

mail.attach("attachment.jpg");          // relative to the current directory
mail.attach("D:\\adir\\attachment.jpg") // windows full path
mail.attach("/home/me/myprogram");      // unix full path

When the mail is sent these files will automatically be sent
as part of the message also. Similarly to remove an attachment
call the removeattachment function. e.g.

mail.removeattachment("/home/me/myprogram");

To reset the mailer object (clearing all recipients, message & errors if any)
call the reset function. e.g.

mail.reset( );

To use the mail object again, add recipients and a new message and
optionally a new subject also, then call operator( )( ) to have the new
message mailed to the new recipients. The nameserver/smtpserver
can be changed using the setserver function, simararily the sender
can be changed using the setsender function. reset does not
change these values, so sending to a different server or using a
different nameserver will need setserver being called and
likewise to change who the mail is from will need a call to setsender.

If the server to which you are connecting requires authentication set
the username/password pair before calling send. e.g.

mail.username("loginname");
mail.password("secret");

To stop using authentication call the username function with the empty string.

mail.username("");

Currently only LOGIN and PLAIN authentication are supported, LOGIN by default,
to set to PLAIN call the authtype function

mail.authtype("mailer::PLAIN");

mailer public interface:
construction

// if MXLookup is true:
// server is a nameserver to lookup an MX record by.
// if MXLookup is false.
// server is an SMTP server which will be attempted directly for mailing
// if an IP address is not found, either MX record or direct to SMTP server,
// an attempt will be made to send mail directly to the server in the mail address.
// e.g. mail to fred@somewhere.com will have a connection attempt made directly to:
// somewhere.com
mailer(const char* TOaddress, const char* FROMaddress,
       const char* Subject, const std::vector<char>& Message,
       const char* server = "127.0.0.1", // default to localhost
       unsigned short Port = SMTP_PORT,  // default SMTP port (25)
       bool MXLookup = true);
mailer(const char* TOaddress, const char* FROMaddress,
       const char* Subject, const char* Message,
       const char* server = "127.0.0.1", // default to localhost
       unsigned short Port = SMTP_PORT,  // default SMTP port (25)
       bool MXLookup = true);
mailer(bool MXLookup = false, unsigned short Port = SMTP_PORT);
~mailer( );

// returns true if the address is added to the recipient list.
// recipient_type must be in the range mailer::TO -> mailer::BCC if
// not recipient_type defaults to BCC (blind copy), see const enum below.
bool addrecipient(const std::string& newrecipient, short recipient_type = mailer::TO /*CC, BCC*/);

// remove an attachment from the list of attachments.
// returns false if !filename.length() or
// the file is not attached or there are no attachments.
bool removerecipient(const std::string& recipient);

// remove all recipients from the recipient list.
void clearrecipients( );

// attach a file to the mail. (MIME 1.0)
// returns false if !filename.length() or
// the file could not be opened for reading...etc.
// The file is unchanged, i.e. opened read-only.
bool attach(const std::string& filename);

// remove an attachment from the list of attachments.
// returns false if !filename.length() or
// the file is not attached or there are no attachments.
bool removeattachment(const std::string& filename);

// clear all attachments from the recipient list.
void clearattachments( );

// Set a new message (replacing the old)
// will return false and not change the message if newmessage is empty.
bool setmessage(const std::string& newmessage);
bool setmessage(const std::vector<char>& newmessage);

// will return false if newSubject is empty.
bool setsubject(const std::string& newSubject);

// Set a new HTML message (replacing the old)
// will return false and not change the HTML message if newmessage is empty.
bool setmessageHTML(const std::string& newmessage);
bool setmessageHTML(const std::vector<char>& newmessage);
// Using a file as the html data.
bool setmessageHTMLfile(const std::string& filename);

// clear all recipients, message, attachments, errors.
// does not reset the name/smtp server (use setserver for this)
// does not set the senders address (use setsender for this)
void reset( );

// sets the nameserver or smtp server to connect to
// dependant on the constructor call, i.e. whether
// 'lookupMXRecord' was set to false or true.
// (see constructor comment for details)
bool setserver(const std::string& nameserver_or_smtpserver);

// sets the senders address (fromAddress variable)
bool setsender(const std::string& newsender);

// call this operator to have the mail mailed.
// this is to facilitate using multiple threads
// i.e. using boost::thread. ( see http://www.boost.org )
//
// e.g.
// mailer mail(args...);
// boost::thread thrd(mail); // operator( )( ) implicitly called.
// thrd.join( ); // if needed.
//
// or:
// mailer mail(args...);
// mail.operator( )( );
void operator( )( );
void send( ); // implicitly call "operator( )( )

// returns the return code sent by the smtp server or a local error.
// this is the only way to find if there is an error in processing.
// if the mail is sent correctly this string will begin with 250
// see smtp RFC 821 section 4.2.2 for response codes.
const std::string& response( ) const;

// set the username for authentication.
// If this function is called with a non empty string
// jwSMTP will try to use authentication.
// To not use authentication after this, call again
// with the empty string e.g.
// mailerobject.username("");
void username(const std::string& User);

// set the password for authentication
void password(const std::string& Pass);

// set the authentication type
// currently LOGIN or PLAIN only.
// The default login type is LOGIN, set in the constructor
void authtype(const enum authtype Type);