Code Sample: Emailer.as

package com.yoeunpen.net
{
	/**
	 * The Emailer class facilitates the process of generating an email packet
	 * and sending that request to a REST web service. The server returns an XML response.
	 *
	 * @author Yoeun Pen
	 * @version 2.0
	 * @usage Designed to work in tandem with my custom PHP script, with its proprietary URL format and XML response schema.
	 *
	 * URL format:
	 * 		fromEmail
	 * 		fromName (optional)
	 * 		subject
	 * 		message
	 *
	 * 		toEmail[0][email]
	 * 		toEmail[0][name]
	 * 		toEmail[1][email]
	 * 		toEmail[1][name]
	 * 		...
	 * 		toEmail[n][email]
	 * 		toEmail[n][name]
	 *
	 * 		ccEmail[0][email]
	 * 		...
	 *
	 * 		bccEmail[0][email]
	 * 		...
	 *
	 * XML response:
	 * 		<success>1</success>
	 *   or
	 * 		<error>Lorem ipsum</error>
	 */
	
	import flash.events.EventDispatcher;
	import flash.events.Event;
	import flash.net.URLLoader;
	import flash.net.URLRequest;
	import flash.events.IOErrorEvent;
	
	public class Emailer extends EventDispatcher
	{
		// ==========
		// properties
		// ==========
	
		private var _webServiceUrl:String;
		
		// basic email data
		public var fromName:String; // optional
		public var fromEmail:String;
		public var subject:String;
		public var message:String;
		
		// recipients (optional - can be specified in the PHP service)
		private var _toEmails:Array;
		private var _ccEmails:Array;
		private var _bccEmails:Array;
		
		public var isHtml:Boolean = false;
		public var requireTo:Boolean = false;
		public var requireFromName:Boolean = false;
		public var requireSubject:Boolean = false;
		
		// ==========
		// constructor
		// ==========
		
		/**
		 * Constructor
		 *
		 * @param	webServiceUrl
		 */
		function Emailer(webServiceUrl:String)
		{
			_webServiceUrl = webServiceUrl;
			
			_toEmails = new Array();
			_ccEmails = new Array();
			_bccEmails = new Array();
		}
		
		// ==========
		// Add email recipients (Standard, CC and BCC)
		// ==========
		
		public function addAddress(toEmail:String, toName:String):void
		{
			_toEmails.push({email:toEmail, name:toName});
		}
		
		public function addCCAddress(ccEmail:String, ccName:String):void
		{
			_ccEmails.push({email:ccEmail, name:ccName});
		}
		
		public function addBCCAddress(bccEmail:String, bccName:String):void
		{
			_bccEmails.push({email:bccEmail, name:bccName});
		}
		
		// ==========
		// Methods associated with sending the request (including event listeners)
		// ==========
		
		/**
		 * Packages up the email data and sends a request to server.
		 * This process dispatches either an EmailerEvent.SENT or EmailerEvent.ERROR event
		 */
		public function send():void
		{
			if (!ready)
			{
				dispatchEvent(new EmailerEvent(EmailerEvent.ERROR, EmailerEvent.MISSING_FIELDS, "Please fill out all required fields."));
				return;
			}
			
			// ==========
			
			// generate URL-formatted query string
			var urlParams:String = '';
			
			urlParams += '&fromEmail='+escape(fromEmail);
			urlParams += '&fromName='+escape(fromName);
			urlParams += mergeEmailsToString(_toEmails, 'toEmail');
			urlParams += mergeEmailsToString(_ccEmails, 'ccEmail');
			urlParams += mergeEmailsToString(_bccEmails, 'bccEmail');
			urlParams += '&subject='+escape(subject);
			urlParams += '&message=' + escape(message);
			
			// strip first ampersand
			urlParams = urlParams.substr(1);
			
			// ==========
			
			// send request to server
			var xmlConn:URLLoader = new URLLoader();
			xmlConn.addEventListener(Event.COMPLETE, onSendComplete);
			xmlConn.addEventListener(IOErrorEvent.IO_ERROR, onSendError);
			xmlConn.load(new URLRequest(_webServiceUrl + '?' + urlParams));
		}
		
		/**
		 * Parses the XML response and dispatches SENT or ERROR EmailerEvents
		 *
		 * @param	e	Event.COMPLETE object
		 */
		private function onSendComplete(e:Event):void
		{
			try
			{
				var xmlRoot:XML = new XML(e.target.data);
				
				if (xmlRoot=="1")
				{
					dispatchEvent(new EmailerEvent(EmailerEvent.SENT));
				}
				else
				{
					dispatchEvent(new EmailerEvent(EmailerEvent.ERROR, EmailerEvent.CANNOT_SEND, String(xmlRoot)));
				}
			}
			catch (TypeError)
			{
				dispatchEvent(new EmailerEvent(EmailerEvent.ERROR, EmailerEvent.XML_ERROR, "Malformed XML response from server."));
			}
		}
		
		/**
		 * Callback function is triggered when the service cannot be found (e.g., incorrect URL)
		 *
		 * @param	e	IOErrorEvent.IO_ERROR event
		 */
		private function onSendError(e:IOErrorEvent):void
		{
			dispatchEvent(new EmailerEvent(EmailerEvent.ERROR, EmailerEvent.CONNECTION_ERROR, "Connection to Emailer service failed. Please check the URL."));
		}
		
		// ==========
		// Private utility methods
		// ==========
		
		/**
		 * Validates an email address. Supports .co.uk and other non-US domain names;
		 *
		 * @param	addr	Email address to check
		 * @return	True if email address is in a valid format
		 */
		private function validEmail(addr:String):Boolean
		{
			return addr!="" && addr.match(/^(\w|\-|\_|\.)+\@((\w|\-|\_)+\.)+[a-zA-Z]{2,}$/i);
		}
		
		/**
		 * Returns true if the emailer has all required fields and is ready to be sent
		 */
		private function get ready():Boolean
		{
			var ok:Boolean = validEmail(fromEmail) && message.length>0;
			
			if (requireTo)
				ok = ok && _toEmails.length>0;
			if (requireFromName)
				ok = ok && fromName.length>0;
			if (requireSubject)
				ok = ok && subject.length>0;
			
			return ok;
		}
		
		/**
		 * Takes in an array of mail addresses (and possibly names)
		 * and combines them to generate a valid URL-formatted string
		 *
		 * @param	emails		Array of email addresses and names (optional), whose elements are objects in the form {email:"foo@bar.com", name:="foo bar"}
		 * @param	fieldName	Name of query string variable
		 * @return	URL formatted string
		 */
		private function mergeEmailsToString(emails:Array, fieldName:String):String
		{
			var str:String = '';
			for (var i=0; i<emails.length; i++)
			{
				str += '&'+fieldName+'['+i+'][email]='+escape(emails[i].email);
				
				if (emails[i].name && emails[i].name!='')
					str += '&'+fieldName+'['+i+'][name]='+escape(emails[i].name);
			}
			
			return str;
		}
	}
}