Gitiles
Code Review Sign In
www.giggi.me / code-igniter-v3-giggi / a145e9204a29c8965c7440435f599263e418bb77 / . / user_guide / libraries / email.html
blob: 88c63f046a8c85cbe08881e545db013fc38f0c7e [file] [log] [blame]
Derek Allard39b622d2008-01-16 21:10:09 +0000[diff] [blame]1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
Derek Allardafd99ac2008-01-19 19:59:14 +0000[diff] [blame]2<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
Derek Allard39b622d2008-01-16 21:10:09 +0000[diff] [blame]3<head>
4
Derek Allard8039d4c2008-05-31 02:47:56 +0000[diff] [blame]5<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
Derek Jonesfd93d222008-05-06 15:18:50 +0000[diff] [blame]6<title>Email Class : CodeIgniter User Guide</title>
Derek Allard39b622d2008-01-16 21:10:09 +0000[diff] [blame]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
Derek Allard39b622d2008-01-16 21:10:09 +0000[diff] [blame]16<meta http-equiv='expires' content='-1' />
17<meta http-equiv= 'pragma' content='no-cache' />
18<meta name='robots' content='all' />
Derek Allard3d879d52008-01-18 19:41:32 +0000[diff] [blame]19<meta name='author' content='ExpressionEngine Dev Team' />
Derek Allard39b622d2008-01-16 21:10:09 +0000[diff] [blame]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.jpg" width="153" height="44" 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 Jones6b7b11f2008-05-06 16:07:27 +0000[diff] [blame]31<td><h1>CodeIgniter User Guide Version 1.6.2</h1></td>
Derek Allard39b622d2008-01-16 21:10:09 +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">
Derek Jones7a9193a2008-01-21 18:39:20 +0000[diff] [blame]43<a href="http://codeigniter.com/">CodeIgniter Home</a> &nbsp;&#8250;&nbsp;
Derek Allard39b622d2008-01-16 21:10:09 +0000[diff] [blame]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>
66<li>Multiple recipients</li>
67<li>CC and BCCs</li>
68<li>HTML or Plaintext email</li>
69<li>Attachments</li>
70<li>Word wrapping</li>
71<li>Priorities</li>
72<li>BCC Batch Mode, enabling large email lists to be broken into small BCC batches.</li>
73<li>Email Debugging tools</li>
74</ul>
75
76
77<h2>Sending Email</h2>
78
79<p>Sending email is not only simple, but you can configure it on the fly or set your preferences in a config file.</p>
80
81<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
82<a href="../general/controllers.html">controllers</a>.</p>
83
84<code>$this->load->library('email');<br />
85<br />
Derek Jonesff845f92008-06-26 17:05:55 +0000[diff] [blame]86$this->email->from('your@example.com', 'Your Name');<br />
Derek Allard39b622d2008-01-16 21:10:09 +0000[diff] [blame]87$this->email->to('someone@example.com'); <br />
88$this->email->cc('another@another-example.com'); <br />
89$this->email->bcc('them@their-example.com'); <br />
90<br />
91$this->email->subject('Email Test');<br />
92$this->email->message('Testing the email class.'); <br />
93<br />
94$this->email->send();<br />
95<br />
96echo $this->email->print_debugger();</code>
97
98
99
100
101<h2>Setting Email Preferences</h2>
102
103<p>There are 17 different preferences available to tailor how your email messages are sent. You can either set them manually
104as described here, or automatically via preferences stored in your config file, described below:</p>
105
106<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>
107
108<code>$config['protocol'] = 'sendmail';<br />
109$config['mailpath'] = '/usr/sbin/sendmail';<br />
110$config['charset'] = 'iso-8859-1';<br />
111$config['wordwrap'] = TRUE;<br />
112<br />
113$this->email->initialize($config);</code>
114
115<p><strong>Note:</strong> Most of the preferences have default values that will be used if you do not set them.</p
116
117><h3>Setting Email Preferences in a Config File</h3>
118
119<p>If you prefer not to set preferences using the above method, you can instead put them into a config file.
120Simply create a new file called the <var>email.php</var>, add the <var>$config</var>
121array in that file. Then save the file at <var>config/email.php</var> and it will be used automatically. You
122will NOT need to use the <dfn>$this->email->initialize()</dfn> function if you save your preferences in a config file.</p>
123
124
125
126
127<h2>Email Preferences</h2>
128
129<p>The following is a list of all the preferences that can be set when sending email.</p>
130
131
132<table cellpadding="0" cellspacing="1" border="0" style="width:100%" class="tableborder">
133<tr>
134<th>Preference</th>
135<th>Default&nbsp;Value</th>
136<th>Options</th>
137<th>Description</th>
138</tr><tr>
139<td class="td"><strong>useragent</strong></td><td class="td">CodeIgniter</td><td class="td">None</td><td class="td">The "user agent".</td>
140</tr><tr>
141<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>
142</tr><tr>
143<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>
144</tr><tr>
145<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>
146</tr><tr>
147<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>
148</tr><tr>
149<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>
150</tr><tr>
151<td class="td"><strong>smtp_port</strong></td><td class="td">25</td><td class="td">None</td><td class="td">SMTP Port.</td>
152</tr><tr>
153<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>
154</tr><tr>
155<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>
156</tr><tr>
157<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>
158</tr><tr>
159<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>
160</tr><tr>
161<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>
162</tr><tr>
163<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>
164</tr><tr>
165<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 Allard7c53be42008-04-22 12:02:43 +0000[diff] [blame]166</tr>
167<tr>
168 <td class="td"><strong>crlf</strong></td>
169 <td class="td">\n</td>
170 <td class="td">&quot;\r\n&quot; or &quot;\n&quot; or &quot;\r&quot;</td>
171 <td class="td">Newline character. (Use &quot;\r\n&quot; to comply with RFC 822).</td>
172</tr>
173<tr>
174<td class="td"><strong>newline</strong></td><td class="td">\n</td>
175<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>
Derek Allard39b622d2008-01-16 21:10:09 +0000[diff] [blame]176</tr><tr>
177<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>
178</tr><tr>
179<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>
180</tr>
181</table>
182
183
184<h2>Email Function Reference</h2>
185
186<h3>$this->email->from()</h3>
187<p>Sets the email address and name of the person sending the email:</p>
Derek Jonesff845f92008-06-26 17:05:55 +0000[diff] [blame]188<code>$this->email->from('<var>you@example.com</var>', '<var>Your Name</var>');</code>
Derek Allard39b622d2008-01-16 21:10:09 +0000[diff] [blame]189
190<h3>$this->email->reply_to()</h3>
191<p>Sets the reply-to address. If the information is not provided the information in the "from" function is used. Example:</p>
Derek Jonesff845f92008-06-26 17:05:55 +0000[diff] [blame]192<code>$this->email->reply_to('<var>you@example.com</var>', '<var>Your Name</var>');</code>
Derek Allard39b622d2008-01-16 21:10:09 +0000[diff] [blame]193
194
195<h3>$this->email->to()</h3>
196<p>Sets the email address(s) of the recipient(s). Can be a single email, a comma-delimited list or an array:</p>
197
198<code>$this->email->to('<var>someone@example.com</var>');</code>
199<code>$this->email->to('<var>one@example.com</var>, <var>two@example.com</var>, <var>three@example.com</var>');</code>
200
201<code>$list = array('<var>one@example.com</var>', '<var>two@example.com</var>', '<var>three@example.com</var>');<br />
202<br />
203$this->email->to(<var>$list</var>);</code>
204
205<h3>$this->email->cc()</h3>
206<p>Sets the CC email address(s). Just like the "to", can be a single email, a comma-delimited list or an array.</p>
207
208<h3>$this->email->bcc()</h3>
209<p>Sets the BCC email address(s). Just like the "to", can be a single email, a comma-delimited list or an array.</p>
210
211
212<h3>$this->email->subject()</h3>
213<p>Sets the email subject:</p>
214<code>$this->email->subject('<var>This is my subject</var>');</code>
215
216<h3>$this->email->message()</h3>
217<p>Sets the email message body:</p>
218<code>$this->email->message('<var>This is my message</var>');</code>
219
220<h3>$this->email->set_alt_message()</h3>
221<p>Sets the alternative email message body:</p>
222<code>$this->email->set_alt_message('<var>This is the alternative message</var>');</code>
223
224<p>This is an optional message string which can be used if you send HTML formatted email. It lets you specify an alternative
225message with no HTML formatting which is added to the header string for people who do not accept HTML email.
226If you do not set your own message CodeIgniter will extract the message from your HTML email and strip the tags.</p>
227
228
229
230<h3>$this->email->clear()</h3>
231<p>Initializes all the email variables to an empty state. This function is intended for use if you run the email sending function
232in a loop, permitting the data to be reset between cycles.</p>
233<code>foreach ($list as $name => $address)<br />
234{<br />
235&nbsp;&nbsp;&nbsp;&nbsp;$this->email->clear();<br /><br />
236
237&nbsp;&nbsp;&nbsp;&nbsp;$this->email->to($address);<br />
Derek Jonesff845f92008-06-26 17:05:55 +0000[diff] [blame]238&nbsp;&nbsp;&nbsp;&nbsp;$this->email->from('your@example.com');<br />
Derek Allard39b622d2008-01-16 21:10:09 +0000[diff] [blame]239&nbsp;&nbsp;&nbsp;&nbsp;$this->email->subject('Here is your info '.$name);<br />
240&nbsp;&nbsp;&nbsp;&nbsp;$this->email->message('Hi '.$name.' Here is the info you requested.');<br />
241&nbsp;&nbsp;&nbsp;&nbsp;$this->email->send();<br />
242}</code>
243
244<p>If you set the parameter to TRUE any attachments will be cleared as well:</p>
245
246<code>$this->email->clear(TRUE);</code>
247
248
249<h3>$this->email->send()</h3>
250<p>The Email sending function. Returns boolean TRUE or FALSE based on success or failure, enabling it to be used
251conditionally:</p>
252
Derek Jones0b59f272008-05-13 04:22:33 +0000[diff] [blame]253<code>if ( ! $this->email->send())<br />
Derek Allard39b622d2008-01-16 21:10:09 +0000[diff] [blame]254{<br />
255&nbsp;&nbsp;&nbsp;&nbsp;// Generate error<br />
256}</code>
257
258
259<h3>$this->email->attach()</h3>
260<p>Enables you to send an attachment. Put the file path/name in the first parameter. Note: Use a file path, not a URL.
261For multiple attachments use the function multiple times. For example:</p>
262
263<code>$this->email->attach('/path/to/photo1.jpg');<br />
264$this->email->attach('/path/to/photo2.jpg');<br />
265$this->email->attach('/path/to/photo3.jpg');<br />
266<br />
267$this->email->send();</code>
268
269
270<h3>$this->email->print_debugger()</h3>
271<p>Returns a string containing any server messages, the email headers, and the email messsage. Useful for debugging.</p>
272
273
274<h2>Overriding Word Wrapping</h2>
275
276<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
277get wrapped too, causing it to become un-clickable by the person receiving it. CodeIgniter lets you manually override
278word wrapping within part of your message like this:</p>
279
280<code>The text of your email that<br />
281gets wrapped normally.<br />
282<br />
Derek Jonesff845f92008-06-26 17:05:55 +0000[diff] [blame]283<var>{unwrap}</var>http://example.com/a_long_link_that_should_not_be_wrapped.html<var>{/unwrap}</var><br />
Derek Allard39b622d2008-01-16 21:10:09 +0000[diff] [blame]284<br />
285More text that will be<br />
286wrapped normally.</code>
287
288<p>Place the item you do not want word-wrapped between: <var>{unwrap}</var> <var>{/unwrap}</var></p>
289
290
291</div>
292<!-- END CONTENT -->
293
294
295<div id="footer">
296<p>
297Previous Topic:&nbsp;&nbsp;<a href="database/index.html">Database Class</a>
298&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
299<a href="#top">Top of Page</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
300<a href="../index.html">User Guide Home</a>&nbsp;&nbsp;&nbsp;&middot;&nbsp;&nbsp;
301Next Topic:&nbsp;&nbsp;<a href="encryption.html">Encryption Class</a>
302</p>
Derek Jones07870432008-02-13 03:49:26 +0000[diff] [blame]303<p><a href="http://codeigniter.com">CodeIgniter</a> &nbsp;&middot;&nbsp; Copyright &#169; 2006-2008 &nbsp;&middot;&nbsp; <a href="http://ellislab.com/">Ellislab, Inc.</a></p>
Derek Allard39b622d2008-01-16 21:10:09 +0000[diff] [blame]304</div>
305
306</body>
307</html>