summaryrefslogtreecommitdiffstats
path: root/user_guide_src/source/libraries/email.rst
blob: 1d9d2c1715c3343315eaf8480eba56f6d94f7422 (plain)
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
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
###########
Email Class
###########

CodeIgniter's robust Email Class supports the following features:

-  Multiple Protocols: Mail, Sendmail, and SMTP
-  TLS and SSL Encryption for SMTP
-  Multiple recipients
-  CC and BCCs
-  HTML or Plaintext email
-  Attachments
-  Word wrapping
-  Priorities
-  BCC Batch Mode, enabling large email lists to be broken into small
   BCC batches.
-  Email Debugging tools

.. contents::
  :local:

.. raw:: html

  <div class="custom-index container"></div>

***********************
Using the Email Library
***********************

Sending Email
=============

Sending email is not only simple, but you can configure it on the fly or
set your preferences in a config file.

Here is a basic example demonstrating how you might send email. Note:
This example assumes you are sending the email from one of your
:doc:`controllers <../general/controllers>`.

::

	$this->load->library('email');

	$this->email->from('your@example.com', 'Your Name');
	$this->email->to('someone@example.com');
	$this->email->cc('another@another-example.com');
	$this->email->bcc('them@their-example.com');

	$this->email->subject('Email Test');
	$this->email->message('Testing the email class.');

	$this->email->send();

Setting Email Preferences
=========================

There are 21 different preferences available to tailor how your email
messages are sent. You can either set them manually as described here,
or automatically via preferences stored in your config file, described
below:

Preferences are set by passing an array of preference values to the
email initialize method. Here is an example of how you might set some
preferences::

	$config['protocol'] = 'sendmail';
	$config['mailpath'] = '/usr/sbin/sendmail';
	$config['charset'] = 'iso-8859-1';
	$config['wordwrap'] = TRUE;

	$this->email->initialize($config);

.. note:: Most of the preferences have default values that will be used
	if you do not set them.

Setting Email Preferences in a Config File
------------------------------------------

If you prefer not to set preferences using the above method, you can
instead put them into a config file. Simply create a new file called the
email.php, add the $config array in that file. Then save the file at
config/email.php and it will be used automatically. You will NOT need to
use the ``$this->email->initialize()`` method if you save your
preferences in a config file.

Email Preferences
=================

The following is a list of all the preferences that can be set when
sending email.

=================== ====================== ============================ =======================================================================
Preference          Default Value          Options                      Description
=================== ====================== ============================ =======================================================================
**useragent**       CodeIgniter            None                         The "user agent".
**protocol**        mail                   mail, sendmail, or smtp      The mail sending protocol.
**mailpath**        /usr/sbin/sendmail     None                         The server path to Sendmail.
**smtp_host**       No Default             None                         SMTP Server Address.
**smtp_user**       No Default             None                         SMTP Username.
**smtp_pass**       No Default             None                         SMTP Password.
**smtp_port**       25                     None                         SMTP Port.
**smtp_timeout**    5                      None                         SMTP Timeout (in seconds).
**smtp_keepalive**  FALSE                  TRUE or FALSE (boolean)      Enable persistent SMTP connections.
**smtp_crypto**     No Default             tls or ssl                   SMTP Encryption
**wordwrap**        TRUE                   TRUE or FALSE (boolean)      Enable word-wrap.
**wrapchars**       76                                                  Character count to wrap at.
**mailtype**        text                   text or html                 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.
**charset**         ``$config['charset']``                              Character set (utf-8, iso-8859-1, etc.).
**validate**        FALSE                  TRUE or FALSE (boolean)      Whether to validate the email address.
**priority**        3                      1, 2, 3, 4, 5                Email Priority. 1 = highest. 5 = lowest. 3 = normal.
**crlf**            \\n                    "\\r\\n" or "\\n" or "\\r"   Newline character. (Use "\\r\\n" to comply with RFC 822).
**newline**         \\n                    "\\r\\n" or "\\n" or "\\r"   Newline character. (Use "\\r\\n" to comply with RFC 822).
**bcc_batch_mode**  FALSE                  TRUE or FALSE (boolean)      Enable BCC Batch Mode.
**bcc_batch_size**  200                    None                         Number of emails in each BCC batch.
**dsn**             FALSE                  TRUE or FALSE (boolean)      Enable notify message from server
=================== ====================== ============================ =======================================================================

Overriding Word Wrapping
========================

If you have word wrapping enabled (recommended to comply with RFC 822)
and you have a very long link in your email it can get wrapped too,
causing it to become un-clickable by the person receiving it.
CodeIgniter lets you manually override word wrapping within part of your
message like this::

	The text of your email that
	gets wrapped normally.

	{unwrap}http://example.com/a_long_link_that_should_not_be_wrapped.html{/unwrap}

	More text that will be
	wrapped normally.


Place the item you do not want word-wrapped between: {unwrap} {/unwrap}

***************
Class Reference
***************

.. class:: CI_Email

	.. method:: from($from[, $name = ''[, $return_path = NULL]])

		:param string $from: "From" email address
		:param string $name: "From" display name
		:param string $return_path: optional email address to redirect undelivered email
		:returns: CI_Email object for method chaining

		Sets the email address and name of the person sending the email::

			$this->email->from('you@example.com', 'Your Name');

		You can also set a Return-Path, to help redirect undelivered mail::

			$this->email->from('you@example.com', 'Your Name', 'returned_emails@example.com');

		.. note:: Return-Path can't be used if you've configured 'smtp' as
			your protocol.


	.. method:: reply_to($replyto[, $name = ''])

		:param string $replyto: email address for replies
		:param string $name: display name for reply email address
		:returns: CI_Email object for method chaining

		Sets the reply-to address. If the information is not provided the
		information in the :meth:from method is used. Example::

			$this->email->reply_to('you@example.com', 'Your Name');


	.. method:: to($to)

		:param mixed $to: comma delimited string or array of email addresses
		:returns: CI_Email object for method chaining

		Sets the email address(s) of the recipient(s). Can be a single email
		, a comma-delimited list or an array::

			$this->email->to('someone@example.com');

		::

			$this->email->to('one@example.com, two@example.com, three@example.com');

		::

			$list = array('one@example.com', 'two@example.com', 'three@example.com');

			$this->email->to($list);


	.. method:: cc($cc)

		:param mixed $cc: comma delimited string or array of email addresses
		:returns: CI_Email object for method chaining

		Sets the CC email address(s). Just like the "to", can be a single
		email, a comma-delimited list or an array.


	.. method:: bcc($bcc, $limit = '')

		:param mixed $bcc: comma delimited string or array of email addresses
		:param int $limit: Maximum number of emails to send per batch
		:returns: CI_Email object for method chaining

		Sets the BCC email address(s). Just like the "to", can be a single
		email, a comma-delimited list or an array.

		If ``$limit`` is set, "batch mode" will be enabled, which will send
		the emails to batches, with each batch not exceeding the specified
		``$limit``.


	.. method:: subject($subject)

		:param string $subject: email subject line
		:returns: CI_Email object for method chaining

		Sets the email subject::

			$this->email->subject('This is my subject');


	.. method:: message($body)

		:param string $body: email body
		:returns: CI_Email object for method chaining

		Sets the email message body::

			$this->email->message('This is my message');


	.. method:: set_alt_message([$str = ''])

		:param string $str: alternate email body
		:returns: CI_Email object for method chaining

		Sets the alternative email message body::

			$this->email->set_alt_message('This is the alternative message');

		This is an optional message string which can be used if you send
		HTML formatted email. It lets you specify an alternative message
		with no HTML formatting which is added to the header string for
		people who do not accept HTML email. If you do not set your own
		message CodeIgniter will extract the message from your HTML email
		and strip the tags.


	.. method:: set_header($header, $value)

		:param string $header: header name
		:param string $value: header value
		:returns: void

		Appends additional headers to the e-mail::

			$this->email->set_header('Header1', 'Value1');
			$this->email->set_header('Header2', 'Value2');


	.. method:: clear([$clear_attachments = FALSE])

		:param bool $clear_attachments: whether or not to clear attachments

		Initializes all the email variables to an empty state. This method
		is intended for use if you run the email sending method in a loop,
		permitting the data to be reset between cycles.

		::

			foreach ($list as $name => $address)
			{
				$this->email->clear();

				$this->email->to($address);
				$this->email->from('your@example.com');
				$this->email->subject('Here is your info '.$name);
				$this->email->message('Hi '.$name.' Here is the info you requested.');
				$this->email->send();
			}

		If you set the parameter to TRUE any attachments will be cleared as
		well::

			$this->email->clear(TRUE);


	.. method:: send([$auto_clear = TRUE])

		:param bool $auto_clear: Whether to :meth:clear automatically
		:returns: bool

		The Email sending method. Returns boolean TRUE or FALSE based on
		success or failure, enabling it to be used conditionally::

			if ( ! $this->email->send())
			{
				// Generate error
			}

		This method will automatically clear all parameters if the request was
		successful. To stop this behaviour pass FALSE::

		 	if ($this->email->send(FALSE))
		 	{
		 		// Parameters won't be cleared
		 	}

		.. note:: In order to use the ``print_debugger()`` method, you need
			to avoid clearing the email parameters.


	.. method:: attach($filename[, $disposition = ''[, $newname = NULL[, $mime = '']]])

		:param string $filename: name of the file
		:param string $disposition: 'disposition' of the attachment. Most
			email clients make their own decision regardless of the MIME
			specification used here. https://www.iana.org/assignments/cont-disp/cont-disp.xhtml
		:param string $newname: custom name to use for the file in the email
		:param string $mime: MIME type to use (useful for buffered data)
		:returns: CI_Email object for method chaining

		Enables you to send an attachment. Put the file path/name in the first
		parameter. Note: Use a file path, not a URL. For multiple attachments
		use the method multiple times. For example::

			$this->email->attach('/path/to/photo1.jpg');
			$this->email->attach('/path/to/photo2.jpg');
			$this->email->attach('/path/to/photo3.jpg');

		To use the default disposition (attachment), leave the second parameter blank,
		otherwise use a custom disposition::

			$this->email->attach('image.jpg', 'inline');

		If you'd like to use a custom file name, you can use the third paramater::

			$this->email->attach('filename.pdf', 'attachment', 'report.pdf');

		If you need to use a buffer string instead of a real - physical - file you can
		use the first parameter as buffer, the third parameter as file name and the fourth
		parameter as mime-type::

			$this->email->attach($buffer, 'attachment', 'report.pdf', 'application/pdf');


	.. method:: print_debugger([$include = array('headers', 'subject', 'body')])

		:param array $include: Which parts of the message to print out
		:returns: string

		Returns a string containing any server messages, the email headers, and
		the email messsage. Useful for debugging.

		You can optionally specify which parts of the message should be printed.
		Valid options are: **headers**, **subject**, **body**.

		Example::

			// You need to pass FALSE while sending in order for the email data
			// to not be cleared - if that happens, print_debugger() would have
			// nothing to output.
			$this->email->send(FALSE);

			// Will only print the email headers, excluding the message subject and body
			$this->email->print_debugger(array('headers'));

		.. note:: By default, all of the raw data will be printed.