EmailYak.cfc - A ColdFusion Wrapper For The Email Yak API
Last week, I started looking at the Email Yak API for creating bidirectional email communication between your web application and your users. In such a workflow, your users communicate with Email Yak using their native email client (GMail, Hotmail, Apple Mail, Yahoo! Mail, Outlook, etc.); your web application communicates with Email Yak using a JSON (JavaScript Object Notation) API and HTTP callbacks (for push notification). The service is really easy to use and provides powerful features like email parsing and unlimited hosting of file attachements. To make it even easier to use, I tried to encapsulate the HTTP interactions in a simple ColdFusion component wrapper - EmailYak.cfc.
View the EmailYak.cfc project on my GitHub account.
The EmailYak.cfc project currently comes with a demonstration of the following features:
- Register Domain
- Register Email Address
- Send Email
- Send Email with Attachments
- Get All Email
- Get New Email
- Get Email
- Get Email List
- Delete Email
- Trigger Callback
The last feature, Trigger Callback, sends an email to the demo account (itself) in order to simulate a new email. Email Yak then parses the new email and pushes a notification out to the callback URL defined in the domain configuration.
Here's an example of one of the demo files that is making use of the EmailYak.cfc ColdFusion component. This sends an email with Base64-encoded attachments:
<!--- Create an instance of the Email Yak wrapper. --->
<cfset emailYak = createObject( "component", "com.emailyak.EmailYak" )
.init( application.apiKey )
/>
<!---
When sending attachments, they need to be encoded as Base64
strings. Therefore, when we read in the binary, we simply have
to encode them.
--->
<cfset attachments = [
{
filename = "alisha_morrow.jpg",
content = toBase64( fileReadBinary( expandPath( "./attachments/alisha_morrow.jpg" ) ) )
},
{
filename = "jen_rish.jpg",
content = toBase64( fileReadBinary( expandPath( "./attachments/jen_rish.jpg" ) ) )
}
] />
<!--- Send an email with attachments. --->
<cfset response = emailYak.sendEmail(
fromAddress = "ben@emailyakcfc.simpleyak.com",
fromName = "Ben Nadel",
toAddress = "ben@bennadel.com",
subject = "This is a test from EmailYak.cfc",
htmlBody = "Email Yak, it really whips the llama's ass.",
textBody = "Email Yak, it really whips the llama's ass.",
attachments = attachments
) />
<!--- Output the response. --->
<cfdump
var="#response#"
label="Send Email Response"
/>
As you can see, the complexities of the HTTP request and the resource definition and the case-sensitivity has been hidden behind a simple sendEmail() method call.
I haven't started using this kind of workflow in production yet; but, I am itching for a chance to incorporate it. I love the idea of creating seamless interactions with my web application users in a way that removes as much friction as possible.
Want to use code from this post? Check out the license.
Reader Comments
Nice. I'm going to try this out and see how it stacks up with mailgun and sendgrid. Thanks for the effort.
Have you been using GitHub all this time without telling me?
@Aaron,
Ha ha, I've only starting using GitHub a bit. I really want to get into it a lot more. I still have a hand-written Git cheat-sheet next to my mouse pad so I can remember what some of the commands are. More so, however, I just like the idea of GitHub as a way to keep my code backed-up and also a place to keep open issues and what not.... you know, all the stuff that I'm probably *supposed* to be doing :D
Let me know what you think of Email Yak - it's the first thing I've tried (as you know). I'd be interested to hear how it compares to other things.
I wonder if we should do a Git/GitHub deep dive one day. I'm in the same boat with sort of understanding it but it's still kind of an unknown.
Especially in the CF community where SVN is still tops, I'm guessing.
I've hijacked this thread enough. We can take it offline.
@Aaron,
That would be awesome. I know only vaguely about the kinds of things that it can do.
is GitHub some sort of versioning software or something?
@Anna,
Yeah, it's live SVN, only different.
Thanks, @Ben, it sounds like there are some differences, such as it has a way of executing scripts or something like that...and/or some sort of a shell, and some extra built-in functionality?