Gitiles
Code Review Sign In
www.giggi.me / code-igniter-v3-giggi / 8b3cf634d94cdd8a11b1f1fcec69bdc2a0f5e71b / . / user_guide / libraries / email.html
blob: de2f1c0c9b649f565f5ea516f2f3da5bb725d1b3 [file] [log] [blame]
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
3<head>
4
5<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
6<title>Email Class : CodeIgniter User Guide</title>
7
8<style type='text/css' media='all'>@import url('../userguide.css');</style>
9<link rel='stylesheet' type='text/css' media='all' href='../userguide.css' />
10
11<script type="text/javascript" src="../nav/nav.js"></script>
12<script type="text/javascript" src="../nav/prototype.lite.js"></script>
13<script type="text/javascript" src="../nav/moo.fx.js"></script>
14<script type="text/javascript" src="../nav/user_guide_menu.js"></script>
15
16<meta http-equiv='expires' content='-1' />
17<meta http-equiv= 'pragma' content='no-cache' />
18<meta name='robots' content='all' />
19<meta name='author' content='ExpressionEngine Dev Team' />
20<meta name='description' content='CodeIgniter User Guide' />
21
22</head>
23<body>
24
25<!-- START NAVIGATION -->
26<div id="nav"><div id="nav_inner"><script type="text/javascript">create_menu('../');</script></div></div>
27<div id="nav2"><a name="top"></a><a href="javascript:void(0);" onclick="myHeight.toggle();"><img src="../images/nav_toggle_darker.jpg" width="154" height="43" border="0" title="Toggle Table of Contents" alt="Toggle Table of Contents" /></a></div>
28<div id="masthead">
29<table cellpadding="0" cellspacing="0" border="0" style="width:100%">
30<tr>
Derek Jonesb8c038a2011-08-20 08:57:14 -0500[diff] [blame]31<td><h1>CodeIgniter User Guide Version 2.0.3</h1></td>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]32<td id="breadcrumb_right"><a href="../toc.html">Table of Contents Page</a></td>
33</tr>
34</table>
35</div>
36<!-- END NAVIGATION -->
37
38
39<!-- START BREADCRUMB -->
40<table cellpadding="0" cellspacing="0" border="0" style="width:100%">
41<tr>
42<td id="breadcrumb">
43<a href="http://codeigniter.com/">CodeIgniter Home</a> &nbsp;&#8250;&nbsp;
44<a href="../index.html">User Guide Home</a> &nbsp;&#8250;&nbsp;
45Email Class
46</td>
47<td id="searchbox"><form method="get" action="http://www.google.com/search"><input type="hidden" name="as_sitesearch" id="as_sitesearch" value="codeigniter.com/user_guide/" />Search User Guide&nbsp; <input type="text" class="input" style="width:200px;" name="q" id="q" size="31" maxlength="255" value="" />&nbsp;<input type="submit" class="submit" name="sa" value="Go" /></form></td>
48</tr>
49</table>
50<!-- END BREADCRUMB -->
51
52<br clear="all" />
53
54
55<!-- START CONTENT -->
56<div id="content">
57
58
59<h1>Email Class</h1>
60
61<p>CodeIgniter's robust Email Class supports the following features:</p>
62
63
64<ul>
65<li>Multiple Protocols: Mail, Sendmail, and SMTP</li>
Radu Potopad67aae2011-09-28 14:25:03 +0300[diff] [blame]66<li>TLS and SSL Encryption for SMTP</li>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]67<li>Multiple recipients</li>
68<li>CC and BCCs</li>
69<li>HTML or Plaintext email</li>
70<li>Attachments</li>
71<li>Word wrapping</li>
72<li>Priorities</li>
73<li>BCC Batch Mode, enabling large email lists to be broken into small BCC batches.</li>
74<li>Email Debugging tools</li>
75</ul>
76
77
78<h2>Sending Email</h2>
79
80<p>Sending email is not only simple, but you can configure it on the fly or set your preferences in a config file.</p>
81
Derek Jones4b9c6292011-07-01 17:40:48 -0500[diff] [blame]82<p>Here is a basic example demonstrating how you might send email. Note: This example assumes you are sending the email from one of your
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]83<a href="../general/controllers.html">controllers</a>.</p>
84
85<code>$this->load->library('email');<br />
86<br />
Barry Mienydd671972010-10-04 16:33:58 +0200[diff] [blame]87$this->email->from('your@example.com', 'Your Name');<br />
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]88$this->email->to('someone@example.com'); <br />
89$this->email->cc('another@another-example.com'); <br />
90$this->email->bcc('them@their-example.com'); <br />
91<br />
92$this->email->subject('Email Test');<br />
93$this->email->message('Testing the email class.'); <br />
94<br />
95$this->email->send();<br />
96<br />
97echo $this->email->print_debugger();</code>
98
99
100
101
102<h2>Setting Email Preferences</h2>
103
104<p>There are 17 different preferences available to tailor how your email messages are sent. You can either set them manually
105as described here, or automatically via preferences stored in your config file, described below:</p>
106
Derek Jones4b9c6292011-07-01 17:40:48 -0500[diff] [blame]107<p>Preferences are set by passing an array of preference values to the email <dfn>initialize</dfn> function. Here is an example of how you might set some preferences:</p>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]108
109<code>$config['protocol'] = 'sendmail';<br />
110$config['mailpath'] = '/usr/sbin/sendmail';<br />
111$config['charset'] = 'iso-8859-1';<br />
112$config['wordwrap'] = TRUE;<br />
113<br />
114$this->email->initialize($config);</code>
115
116<p><strong>Note:</strong> Most of the preferences have default values that will be used if you do not set them.</p
117
118><h3>Setting Email Preferences in a Config File</h3>
119
120<p>If you prefer not to set preferences using the above method, you can instead put them into a config file.
Derek Jones4b9c6292011-07-01 17:40:48 -0500[diff] [blame]121Simply create a new file called the <var>email.php</var>, add the <var>$config</var>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]122array in that file. Then save the file at <var>config/email.php</var> and it will be used automatically. You
123will NOT need to use the <dfn>$this->email->initialize()</dfn> function if you save your preferences in a config file.</p>
124
125
126
127
128<h2>Email Preferences</h2>
129
130<p>The following is a list of all the preferences that can be set when sending email.</p>
131
132
133<table cellpadding="0" cellspacing="1" border="0" style="width:100%" class="tableborder">
134<tr>
135<th>Preference</th>
136<th>Default&nbsp;Value</th>
137<th>Options</th>
138<th>Description</th>
139</tr><tr>
140<td class="td"><strong>useragent</strong></td><td class="td">CodeIgniter</td><td class="td">None</td><td class="td">The "user agent".</td>
141</tr><tr>
142<td class="td"><strong>protocol</strong></td><td class="td">mail</td><td class="td">mail, sendmail, or smtp</td><td class="td">The mail sending protocol.</td>
143</tr><tr>
144<td class="td"><strong>mailpath</strong></td><td class="td">/usr/sbin/sendmail</td><td class="td">None</td><td class="td">The server path to Sendmail.</td>
145</tr><tr>
146<td class="td"><strong>smtp_host</strong></td><td class="td">No Default</td><td class="td">None</td><td class="td">SMTP Server Address.</td>
147</tr><tr>
148<td class="td"><strong>smtp_user</strong></td><td class="td">No Default</td><td class="td">None</td><td class="td">SMTP Username.</td>
149</tr><tr>
150<td class="td"><strong>smtp_pass</strong></td><td class="td">No Default</td><td class="td">None</td><td class="td">SMTP Password.</td>
151</tr><tr>
152<td class="td"><strong>smtp_port</strong></td><td class="td">25</td><td class="td">None</td><td class="td">SMTP Port.</td>
153</tr><tr>
154<td class="td"><strong>smtp_timeout</strong></td><td class="td">5</td><td class="td">None</td><td class="td">SMTP Timeout (in seconds).</td>
155</tr><tr>
Radu Potopad67aae2011-09-28 14:25:03 +0300[diff] [blame]156<td class="td"><strong>smtp_crypto</strong></td><td class="td">No Default</td><td class="td">tls or ssl</td><td class="td">SMTP Encryption.</td>
157</tr><tr>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]158<td class="td"><strong>wordwrap</strong></td><td class="td">TRUE</td><td class="td">TRUE or FALSE (boolean)</td><td class="td">Enable word-wrap.</td>
159</tr><tr>
160<td class="td"><strong>wrapchars</strong></td><td class="td">76</td><td class="td"> </td><td class="td">Character count to wrap at.</td>
161</tr><tr>
Derek Jones4b9c6292011-07-01 17:40:48 -0500[diff] [blame]162<td class="td"><strong>mailtype</strong></td><td class="td">text</td><td class="td">text or html</td><td class="td">Type of mail. If you send HTML email you must send it as a complete web page. Make sure you don't have any relative links or relative image paths otherwise they will not work.</td>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]163</tr><tr>
164<td class="td"><strong>charset</strong></td><td class="td">utf-8</td><td class="td"></td><td class="td">Character set (utf-8, iso-8859-1, etc.).</td>
165</tr><tr>
Derek Jones4b9c6292011-07-01 17:40:48 -0500[diff] [blame]166<td class="td"><strong>validate</strong></td><td class="td">FALSE</td><td class="td">TRUE or FALSE (boolean)</td><td class="td">Whether to validate the email address.</td>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]167</tr><tr>
Derek Jones4b9c6292011-07-01 17:40:48 -0500[diff] [blame]168<td class="td"><strong>priority</strong></td><td class="td">3</td><td class="td">1, 2, 3, 4, 5</td><td class="td">Email Priority. 1 = highest. 5 = lowest. 3 = normal.</td>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]169</tr>
170<tr>
171 <td class="td"><strong>crlf</strong></td>
172 <td class="td">\n</td>
173 <td class="td">&quot;\r\n&quot; or &quot;\n&quot; or &quot;\r&quot;</td>
174 <td class="td">Newline character. (Use &quot;\r\n&quot; to comply with RFC 822).</td>
175</tr>
176<tr>
177<td class="td"><strong>newline</strong></td><td class="td">\n</td>
178<td class="td">"\r\n" or "\n" or &quot;\r&quot;</td><td class="td">Newline character. (Use "\r\n" to comply with RFC 822).</td>
179</tr><tr>
180<td class="td"><strong>bcc_batch_mode</strong></td><td class="td">FALSE</td><td class="td">TRUE or FALSE (boolean)</td><td class="td">Enable BCC Batch Mode.</td>
181</tr><tr>
182<td class="td"><strong>bcc_batch_size</strong></td><td class="td">200</td><td class="td">None</td><td class="td">Number of emails in each BCC batch.</td>
183</tr>
184</table>
185
186
187<h2>Email Function Reference</h2>
188
189<h3>$this->email->from()</h3>
190<p>Sets the email address and name of the person sending the email:</p>
191<code>$this->email->from('<var>you@example.com</var>', '<var>Your Name</var>');</code>
192
193<h3>$this->email->reply_to()</h3>
Derek Jones4b9c6292011-07-01 17:40:48 -0500[diff] [blame]194<p>Sets the reply-to address. If the information is not provided the information in the "from" function is used. Example:</p>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]195<code>$this->email->reply_to('<var>you@example.com</var>', '<var>Your Name</var>');</code>
196
197
198<h3>$this->email->to()</h3>
Derek Jones4b9c6292011-07-01 17:40:48 -0500[diff] [blame]199<p>Sets the email address(s) of the recipient(s). Can be a single email, a comma-delimited list or an array:</p>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]200
201<code>$this->email->to('<var>someone@example.com</var>');</code>
202<code>$this->email->to('<var>one@example.com</var>, <var>two@example.com</var>, <var>three@example.com</var>');</code>
203
204<code>$list = array('<var>one@example.com</var>', '<var>two@example.com</var>', '<var>three@example.com</var>');<br />
205<br />
206$this->email->to(<var>$list</var>);</code>
207
208<h3>$this->email->cc()</h3>
209<p>Sets the CC email address(s). Just like the "to", can be a single email, a comma-delimited list or an array.</p>
210
211<h3>$this->email->bcc()</h3>
212<p>Sets the BCC email address(s). Just like the "to", can be a single email, a comma-delimited list or an array.</p>
213
214
215<h3>$this->email->subject()</h3>
216<p>Sets the email subject:</p>
217<code>$this->email->subject('<var>This is my subject</var>');</code>
218
219<h3>$this->email->message()</h3>
220<p>Sets the email message body:</p>
221<code>$this->email->message('<var>This is my message</var>');</code>
222
223<h3>$this->email->set_alt_message()</h3>
224<p>Sets the alternative email message body:</p>
225<code>$this->email->set_alt_message('<var>This is the alternative message</var>');</code>
226
Derek Jones4b9c6292011-07-01 17:40:48 -0500[diff] [blame]227<p>This is an optional message string which can be used if you send HTML formatted email. It lets you specify an alternative
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]228message with no HTML formatting which is added to the header string for people who do not accept HTML email.
229If you do not set your own message CodeIgniter will extract the message from your HTML email and strip the tags.</p>
230
231
232
233<h3>$this->email->clear()</h3>
Derek Jones4b9c6292011-07-01 17:40:48 -0500[diff] [blame]234<p>Initializes all the email variables to an empty state. This function is intended for use if you run the email sending function
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]235in a loop, permitting the data to be reset between cycles.</p>
236<code>foreach ($list as $name => $address)<br />
237{<br />
238&nbsp;&nbsp;&nbsp;&nbsp;$this->email->clear();<br /><br />
Barry Mienydd671972010-10-04 16:33:58 +0200[diff] [blame]239
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]240&nbsp;&nbsp;&nbsp;&nbsp;$this->email->to($address);<br />
241&nbsp;&nbsp;&nbsp;&nbsp;$this->email->from('your@example.com');<br />
242&nbsp;&nbsp;&nbsp;&nbsp;$this->email->subject('Here is your info '.$name);<br />
243&nbsp;&nbsp;&nbsp;&nbsp;$this->email->message('Hi '.$name.' Here is the info you requested.');<br />
244&nbsp;&nbsp;&nbsp;&nbsp;$this->email->send();<br />
245}</code>
246
247<p>If you set the parameter to TRUE any attachments will be cleared as well:</p>
248
249<code>$this->email->clear(TRUE);</code>
250
251
252<h3>$this->email->send()</h3>
253<p>The Email sending function. Returns boolean TRUE or FALSE based on success or failure, enabling it to be used
254conditionally:</p>
255
256<code>if ( ! $this->email->send())<br />
257{<br />
258&nbsp;&nbsp;&nbsp;&nbsp;// Generate error<br />
259}</code>
260
261
262<h3>$this->email->attach()</h3>
263<p>Enables you to send an attachment. Put the file path/name in the first parameter. Note: Use a file path, not a URL.
264For multiple attachments use the function multiple times. For example:</p>
265
266<code>$this->email->attach('/path/to/photo1.jpg');<br />
267$this->email->attach('/path/to/photo2.jpg');<br />
268$this->email->attach('/path/to/photo3.jpg');<br />
269<br />
270$this->email->send();</code>
271
272
273<h3>$this->email->print_debugger()</h3>
Derek Jones4b9c6292011-07-01 17:40:48 -0500[diff] [blame]274<p>Returns a string containing any server messages, the email headers, and the email messsage. Useful for debugging.</p>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]275
276
277<h2>Overriding Word Wrapping</h2>
278
279<p>If you have word wrapping enabled (recommended to comply with RFC 822) and you have a very long link in your email it can
Derek Jones4b9c6292011-07-01 17:40:48 -0500[diff] [blame]280get wrapped too, causing it to become un-clickable by the person receiving it. CodeIgniter lets you manually override
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]281word wrapping within part of your message like this:</p>
282
283<code>The text of your email that<br />
284gets wrapped normally.<br />
285<br />
286<var>{unwrap}</var>http://example.com/a_long_link_that_should_not_be_wrapped.html<var>{/unwrap}</var><br />
287<br />
288More text that will be<br />
289wrapped normally.</code>
290
291<p>Place the item you do not want word-wrapped between: <var>{unwrap}</var> <var>{/unwrap}</var></p>
292
293
294</div>
295<!-- END CONTENT -->
296
297
298<div id="footer">
299<p>
Derek Allard2976ade2009-02-04 13:22:01 +0000[diff] [blame]300Previous Topic:&nbsp;&nbsp;<a href="../database/index.html">Database Class</a>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]301&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
302<a href="#top">Top of Page</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
303<a href="../index.html">User Guide Home</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
304Next Topic:&nbsp;&nbsp;<a href="encryption.html">Encryption Class</a>
305</p>
Derek Jones898949f2011-01-28 07:42:16 -0600[diff] [blame]306<p><a href="http://codeigniter.com">CodeIgniter</a> &nbsp;&middot;&nbsp; Copyright &#169; 2006 - 2011 &nbsp;&middot;&nbsp; <a href="http://ellislab.com/">EllisLab, Inc.</a></p>
Derek Allard2067d1a2008-11-13 22:59:24 +0000[diff] [blame]307</div>
308
309</body>
Radu Potopad67aae2011-09-28 14:25:03 +0300[diff] [blame]310</html>