ColdFusion CFMailParam's New "Content" Attribute Is Awesome
Posted May 7, 2008 at 9:23 AM by Ben Nadel
As part of the ColdFusion 8.0.1 updater, the CFMailParam tag can now attach files to an email using the Content attribute. When using this, the CFMailParam takes a File attribute and the Content attribute. In this case, the File attribute provides the name of the file as it will appear in the mail attachments list, not the path of the file on the server. The content attribute can take any ColdFusion variable that can be converted to binary data. Like the ColdFusion CFContent tag, this content attribute must use binary data; however, unlike the CFContent tag, the CFMailParam tag will automatically convert variables to binary data for you (when possible). Pretty awesome!
Let's take a look at an example. In this demo, I am going to attach a ColdFusion image object as well as a text value:
- <!---
- Grab an image from flickr.com and create a ColdFusion image
- object via the URL.
- --->
- <cfset objImage = ImageNew(
- "http://farm3.static.flickr.com/2304/2335117561_513d9f8a76_b.jpg"
- ) />
-
- <!--- Resize the image so that it's not too big. --->
- <cfset ImageScaleToFit( objImage, 300, 300 ) />
-
- <!--- Add a border. --->
- <cfset ImageAddBorder( objImage, 2, "##333333" ) />
-
-
- <!--- Create a signature variable. --->
- <cfsavecontent variable="strSignature">
- Ben Nadel
- Kinky Solutions
- www.kinkysolutions.com / www.bennadel.com
- </cfsavecontent>
-
-
-
- <!--- Send out email. --->
- <cfmail
- to="xxx@yyyyyyy.com"
- from="yyy@zzzzz.com"
- subject="Is that your wife???"
- type="html">
-
- Dude, I was doing some research for a business project
- and I came across the attached file. Call me crazy,
- but is that your wife making out with another chick??<br />
- <br />
-
- You better lock that down!<br />
- <br />
-
- <img src="cid:kissing" /><br />
- <br />
-
- Cheers,<br />
- Ben
-
- <!---
- Attach file for inline usage. Use the contents of the
- image object for the value of the CFMailParam. Unlike
- the Content attribute in CFContent, we do not need to
- use a binary variable here.
- --->
- <cfmailparam
- file="wife_kissing_girl.jpg"
- contentid="kissing"
- content="#objImage#"
- disposition="inline"
- />
-
- <!--- Attach signature text. --->
- <cfmailparam
- file="signature.txt"
- content="#Trim( strSignature )#"
- />
-
- </cfmail>
Notice that we are passing the objImage variable directly to the CFMailParam tag. My first instinct was that I had to pass the ImageGetBlob( objImage ) value since that would give me the binary image data (which did work as expected), but after some testing, I found out that the CFMailParam tag will try automatically convert the value to binary for me. Of course, this doesn't always work. If you try to attach a ColdFusion query, for example:
- <!--- Add query to email. --->
- <cfmailparam
- file="query.txt"
- content="#QueryNew( 'id, name, value' )#"
- />
ColdFusion will throw the following exception:
Could not convert the value of type class coldfusion.sql.QueryTable to binary.
As you can see, it is trying to do the binary conversion for you.
Anyway, running the above code resulted in the following GMail email:
| | | | ||
| |  | | ||
| | | |
Notice also that for my signature file, I am not attaching a variable, but rather a trimmed text value. The documentation states that this has to be a ColdFusion variable, but it simply has to be a value that can be converted to binary (which can be an inline text value). Also, I was able to use the CFMailParam and Content tag to create attached files as well as files with an inline disposition (the image displayed within the content of the email itself). This is insanely cool. This, combined with the new Remove attribute is going to make the ColdFusion CFMailParam tag a force to be reconned with! I think these small tweaks are going to have fantastic improvements in the usability of these tags.
Reader Comments
I think it is correctly spelled "reckoned," as in "I reckon you right about that."
In the email generation that we have done from Coldfusion server, we have more routinely relied on <img> tags that call back to our server, rather than sending the image content in the actual email. But, I guess that is because we aren't explicitly sending pictures, more just images for look and feel.
While it is sort of outside the range of your exploration of the content attribute, under what circumstances is it appropriate to send content via email and when should links be provided to pull content off a server?
@Phil,
I am not sure there are any good rules on when to do this. I like the fact that with an embedded image, the images get loaded in the email without prompting the user for permission. This allows me to deliver my brand more effectively (I think).
On the other hand, the attachment does cause problems sometimes. For instance, right now, I am having some mail delivery problems for emails that have embedded images... Adobe is working on a hotfix for this.
BTW... it seems like you can also pass in the filename for attachment...
disposition="attachment; filename=sample.png;"
Ben, have you had luck actually receiving these emails? Running your example as-is doesn't work for me in Thunderbird 2. And based on these tests, image embedding is highly unreliable in general. It's a great technology but has been abused to death by spammers it seems. :(
http://www.campaignmonitor.com/blog/post/1761/embedding-images-in-email/
@Brian,
The Content attribute works for more that just embedded images. It should work for any sort of attached file. I have tried it successfully with attached files.
No... that was my wife.
I took a look at this after your post on Twitter (thanks for suggesting it). I don't think it's possible to do what I need though by using this tag.
I have a file that exists in memory and I'd like to attach that to an email without first having to save it to disk. It's essentially an on demand report generation request and there's NO way I want to manage those files.
@Andy,
Assuming this file exists in memory as either text or binary data, all you have to do is use it in the content attribute of the CFMailParam:
<cfmailparam
content="#YOUR_FILE_VARIABLES#"
file="arbitrary_file_name.ext"
/>
The "file" attribute here is arbitrary - it's just used when ColdFusion actually attaches the given variable to the email.
@Andy,
If you look at this follow-up post:
... you'll see that I am creating a PDF file in memory and then attaching it to the email without ever saving it to a physical file.
@Ben - what happens when using the content attribute if you have mail set to spool? Does CF write out a temp file somewhere or does this force it to send on-the-fly?
@Brian,
I don't know what actually happens behind the scene. But ColdFusion handles it properly.
@Brian,
Also, the CFMailParam "Delete" attribute is great for that stuff as well, if you DO have a physical file:
I really need to read the what's changed documentation better. Thanks Ben! :)
@Brian,
No problem my man. If you have any questions, drop by :)
@Ben
The content tag looks awesome, but I'm getting the error: Attribute validation error for tag CFMAILPARAM.The tag does not allow the attribute(s) CONTENT. The valid attribute(s) are CONTENTID,DISPOSITION,FILE,NAME,TYPE,VALUE.
This led me to believe we were running an older version of coldfusion, but it is 8.01xxx Any ideas?
Thanks a lot though, your examples are always great.
@Kosko,
From the docs, it looks like it was added in the 8.01 updater. Perhaps you are just missing one of the required updates?
I just discovered this "new" content attribute of CF8.01. The Adobe Live Docs don't mention it unless you read the new CF9 docs, so thank you for this blog post.
I was revisiting a CF7 app and needed to improve the effeciency of how the emails are generated. I've now changed it from reading in a file attachment for EVERY iteration of cfmail to storing the file as a binary variable and using the content attribute to take the file from memory instead. So if 50K personalised emails with attachments need to be generated it will require 1 file read instead of 50K.
Ben, is there anything that you haven't blogged about? :-)
@Gary,
That's awesome my man! I've never thought about in terms of file reads before, but that makes perfect sense. Glad that this was able to help :)
Ben,
Mine is version 8 and tried to download the update but still did not recognized content attribute in cfmailparam. May be I installed a wrong update, so many of them not sure which one I need with no clear explanation from adobe. Can anyone help pointing me to the right update file? please?
@Alecken,
If it didn't work with the updater, then I don't have any great advice for you. When things don't work at that level, I definitely feel stuck. Perhaps try the updater again to make sure it worked?
