1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
|
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>LamsonProject: HTML Email Generation</title>
<link rel="stylesheet" href="/styles/global.css" type="text/css" charset="utf-8" />
<link rel="stylesheet" href="/css/code.css" type="text/css" charset="utf-8" />
<!--[if IE 7]>
<style type="text/css" media="screen">
div#column_left ul.sidebar_menu li div.color{
display: none;
}
</style>
<![endif]-->
<link href="/prettify.css" type="text/css" rel="stylesheet" />
<script type="text/javascript" src="/prettify.js"></script>
</head>
<body onload="prettyPrint()">
<div id="content_centered">
<div id="header">
<h1><img id="logo" src="/images/lamson.png" alt="Lamson Project(TM) - Pipes and aliases are so 1970." /></h1>
<ul id="header_menu">
<li><a href="/">Home</a></li>
<li><a href="/blog/">News</a></li>
<li><a href="/feed.xml">Feed</a></li>
<li><a href="/download.html">Download</a></li>
<li><a href="/docs/">Documentation</a></li>
<li><a href="/docs/api/">API</a></li>
</ul>
</div>
<div id="main_content">
<h1>HTML Email Generation</h1>
<p><span class="caps">HTML</span> Email is apparently the killer feature for everyone who uses email.
The first, second, and third question I get asked when I tell people
about Lamson is, “Does it do <span class="caps">HTML</span> email?!” Yes it does, and hopefully
in a very nice clean way that’ll make blasting out all that great
marketing material your users <strong>love</strong> easier than ever.</p>
<blockquote>
<p>The fourth question is whether Lamson handles bounces. <a href="/docs/bounce_detection.html">Yes it does.</a></p>
</blockquote>
<h2>A Few Tips About <span class="caps">HTML</span> Email</h2>
<p>First, you <strong>must</strong> educate your marketing people that your user’s <a href="http://myinboxisnota.tv/">Inbox is not a TV.</a>
I actually run <a href="http://myinboxisnota.tv/">myinboxisnota.tv</a> just to make a point that people who
do marketing have the wrong idea of people’s Inbox experience. It’s your job as the hacker to
educate them and make sure that they know users actually mostly hate <span class="caps">HTML</span> email, and that sending
them an <span class="caps">HTML</span> email is nothing like sending them a commercial on TV.</p>
<p>The next tip is a technical one related to how you have to craft your <span class="caps">HTML</span>. Lamson’s
<a href="http://lamsonproject.org/docs/api/lamson.html-module.html">lamson.html</a> <span class="caps">API</span> actually
helps you get this right, but you need to understand it in order to appreciate what
it does for you.</p>
<p>The rule when crafting your <span class="caps">HTML</span> is that you need to code for browsers of circa 1995
with no ability to use <code>style</code> tags or <code>script</code> tags. Most of the various <span class="caps">HTML</span> viewing
clients strip or disable these making them useless. This means you have to put all
<span class="caps">CSS</span> stylings inline into your <span class="caps">HTML</span>, and you have to rely on “taboo” tags like <code>center</code>
and <code>table</code> for your layout.</p>
<h2>The Structure Of HtmlMail</h2>
<p>The <a href="http://lamsonproject.org/docs/api/lamson.html.HtmlMail-class.html">lamson.html.HtmlMail</a> class
is responsible for generating all your <span class="caps">HTML</span> emails. How it works is you give construct one
with an “outer template” and a <a href="http://sandbox.pocoo.org/clevercss/">CleverCSS</a> template as your
<span class="caps">CSS</span> stylesheet. This builds a generator that you then hand an internal version of your email
to generate the content for each user.</p>
<p>This combination of outer template+CleverCSS and inner markdown content means that you can
use the markdown content also as your text version, since markdown actually looks half-decent
as a text format.</p>
<p>Here’s a simple example that shows this process in action:</p>
<pre class="code prettyprint">
generator = html.HtmlMail("style.css", "html_test.html", {})
resp = generator.respond({}, "content.markdown",
From="zedshaw@zedshaw.com",
To="zedshaw@zedshaw.com",
Subject="Test of an HTML mail.",
Body="content.markdown")
</pre>
<p>First, we make a generator passing in the CleverCSS stylesheet <code>style.css</code>,
and the Jinja2 <span class="caps">HTML</span> template <code>html_test.html</code>. Then we call <code>HtmlMail.respond</code>
to craft a <a href="http://lamsonproject.org/docs/api/lamson.mail.MailResponse-class.html">lamson.mail.MailResponse</a>
that you can then hand to <a href="http://lamsonproject.org/docs/api/lamson.server.Relay-class.html">lamson.server.Relay</a>
for delivery.</p>
<p>There’s also a couple of tricks in the above email. First, notice that the
second parameter is “content.markdown”, but that we also pass in the Body=“content.markdown”.
This little convenience tells the HtmlMail object that you want to reuse the
raw <code>content.markdown</code> file as the text/plain version of the email.</p>
<p>Finally, once you make the generator you can keep calling <code>respond</code> to spit out
each message you want.</p>
<h2>The <span class="caps">HTML</span> <span class="caps">CSS</span> Conversion</h2>
<p>None of the above code shows you what is the nicest part of this <span class="caps">API</span>. The lamson.html
<span class="caps">API</span> will actually take plain <span class="caps">HTML</span> and your CleverCSS and insert the <code>style</code> attributes
into it for you. Let’s look at an example from the unit test (that’s disgusting).
First we have the CleverCSS template:</p>
<pre class="code prettyprint">
body:
margin: 10
padding: 20
background: green - 30
color: blue
h1:
font-size: 3em
h2:
font-size: 2em
color: yellow
h3:
font-size: 1em
p:
padding: 0.3em
background: red
h2:
color: yellow
#bright:
background: black
color: white
.dull:
background: gray
color: black
</pre>
<p>Then we have the raw original HTML:</p>
<pre class="code prettyprint">
<html>
<head>
<title>{{ title }}</title>
</head>
<body style="background: magenta">
<h1 class="bright">{{ title }}</h1>
{{ content }}
<h3 id="dull">All done.</h3>
</body>
</html>
</pre>
<p>Notice this is a template too, and that {{ content }} is your <code>content.markdown</code> file
from the earlier discussion.</p>
<p>Now when you run this (including the content.markdown not shown here), Lamson produces
this:</p>
<pre class="code prettyprint">
<html>
<head>
<title></title>
</head>
<body style="background: magenta; margin: 10; padding: 20; background: #006200; color: blue">
<h1 class="bright" style="font-size: 3em; background: black; color: white"></h1>
<h1 style="font-size: 3em">Hello</h1>
<p style="padding: 0.3em; background: red">I would <em>love</em> for you to tell me what is going on here joe. NOW!</p>
<h2 style="font-size: 2em; color: yellow; color: yellow">Alright</h2>
<p style="padding: 0.3em; background: red">This is the best I can come up with.</p>
<p style="padding: 0.3em; background: red">Zed</p>
<h3 id="dull" style="font-size: 1em; background: gray; color: black">All done.</h3>
</body>
</html>
</pre>
<p>Which, if you code for a Web 2.0 company is probably making your eyes bleed Dijon mustard, but it
works. Lamson has walked your <span class="caps">HTML</span> and inserted all the style tags it could, including
keeping any you already had there.</p>
<h2>Conclusion</h2>
<p>With Lamson <span class="caps">HTML</span> email <span class="caps">API</span> you should be able to blast out all the wonderful <span class="caps">HTML</span> you need
to prop up your sales needs for years to come. It does the best it can to make it easy
to still work in a modern web methodology, but produce the nasty <span class="caps">HTML</span> that has the highest
chance of working in most email clients.</p>
</div>
<div id="column_left">
<ul class="sidebar_menu">
<li>
<div class="item">
<div class="color" style="background-color: #ff0000;"> </div>
<a href="/blog/">Latest News</a>
</div>
</li>
<li>
<div class="item">
<div class="color" style="background-color: #ff9900;"> </div>
<a href="/download.html">Download the Gear</a>
</div>
</li>
<li>
<div class="item">
<div class="color" style="background-color: #99cc00;"> </div>
<a href="/docs/getting_started.html">Getting Started</a>
</div>
</li>
<li>
<div class="item">
<div class="color" style="background-color: #3399ff;"> </div>
<a href="/docs/">Documentation</a>
</div>
</li>
<li>
<div class="item">
<div class="color" style="background-color: #ff3399;"> </div>
<a href="/docs/faq.html">Frequently Asked Questions</a>
</div>
</li>
<li>
<div class="item">
<div class="color" style="background-color: #006699;"> </div>
<a href="/about.html">About Lamson</a>
</div>
</li>
<li>
<div class="item">
<div class="color" style="background-color: #0099cc;"> </div>
<a href="/contact.html">Getting Help with Lamson</a>
</div>
</li>
</ul>
<div class="sidebar_item">
<h3>Quick Start</h3>
<p>See the download instructions for information on getting lamson, and read the getting started instructions to start your own application in less than 10 minutes.</p>
</div>
<br/>
<div class="sidebar_item">
<h3>Mailing Lists</h3>
<p>Lamson hosts its own <a href="/lists/">mailing lists</a> as well as provides a free open mailing list
service for anyone who needs one. Simply send an email to the list you want @librelist.com and it will
get you started.</p>
</div>
</div>
<div id="footer">
<div class="footer_content">
Lamson Project(TM) and all material on this site Copyright © 2009 <a href="http://zedshaw.com/" title="Zed Shaw's blog">Zed Shaw</a> unless otherwise stated.<br/>
Website Designed by <a href="http://kenkeiter.com/">Kenneth Keitner</a> and donated to the LamsonProject.
</div>
</div>
<!-- end:centered_content -->
</div>
</body>
</html>
|
