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