# Email 类
CodeIgniter 拥有强大的 Email 类支持以下特性：
* 多协议：Mail、Sendmail 和 SMTP
* SMTP 协议支持 TLS 和 SSL 加密
* 多个收件人
* 抄送（CC）和密送（BCC）
* HTML 格式邮件 或 纯文本邮件
* 附件
* 自动换行
* 优先级
* 密送批处理模式（BCC Batch Mode），大邮件列表将被分成小批次密送
* Email 调试工具
# 使用 Email 类
# 发送 Email
发送邮件不仅很简单，而且你可以通过参数或通过配置文件设置发送邮件的不同选项。
下面是个简单的例子，用于演示如何发送邮件。注意：这个例子假设你是在某个 控制器 里面发送邮件。
~~~
$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();
~~~
# 设置 Email 参数
有 21 种不同的参数可以用来对你发送的邮件进行配置。你可以像下面这样手工设置它们， 或者通过配置文件自动加载，见下文：
通过向邮件初始化函数传递一个包含参数的数组来设置参数，下面是个如何设置参数的例子:
~~~
$config['protocol'] = 'sendmail';
$config['mailpath'] = '/usr/sbin/sendmail';
$config['charset'] = 'iso-8859-1';
$config['wordwrap'] = TRUE;
$this->email->initialize($config);
~~~
**注解**
如果你不设置，大多数参数将使用默认值。
# 在配置文件中设置 Email 参数
如果你不喜欢使用上面的方法来设置参数，你可以将它们放到配置文件中。你只需要简单的创建一个新文件 email.php ，将 $config 数组放到该文件，然后保存到 config/email.php ，这样它将会自动被加载。 如果你使用配置文件的方式来设置参数，你就不需要使用 $this->email->initialize() 方法了。
# Email 参数
下表为发送邮件时所有可用的参数。
| 参数 | 默认值 | 选项 | 描述 |
| --- | --- | --- | --- |
| useragent | CodeIgniter | None | 用户代理（user agent）|
| protocol | mail | mail, sendmail, or smtp | 邮件发送协议|
| mailpath | /usr/sbin/sendmail | None | 服务器上 Sendmail 的实际路径|
| smtp_host |No Default | None | SMTP 服务器地址 |
| smtp_user | No Default | None | SMTP 用户名|
| smtp_pass | No Default | None | SMTP 密码 |
| smtp_port | 25 |None | SMTP 端口|
| smtp_timeout | 5 |None | SMTP 超时时间（单位：秒）|
| smtp_keepalive | FALSE | TRUE or FALSE (boolean) | 是否启用 SMTP 持久连接|
| smtp_crypto | No Default | tls or ssl | SMTP 加密方式|
| wordwrap | TRUE | TRUE or FALSE (boolean) | 是否启用自动换行 |
| wrapchars | 76 | | 自动换行时每行的最大字符数 |
| mailtype | text| text or html | 邮件类型。如果发送的是 HTML 邮件，必须是一个完整的网页， 确保网页中没有使用相对路径的链接和图片地址，它们在邮件中不能正确显示。 |
| charset | $config['charset'] | | 字符集（utf-8, iso-8859-1 等） |
| validate | FALSE | TRUE or FALSE (boolean) | 是否验证邮件地址 |
| priority |3 |1, 2, 3, 4, 5 | Email 优先级（1 = 最高. 5 = 最低. 3 = 正常） |
|crlf | \n | "\r\n" or "\n" or "\r" | 换行符（使用 "rn" 以遵守 RFC 822）|
| newline | \n | "\r\n" or "\n" or "\r" | 换行符（使用 "rn" 以遵守 RFC 822）|
| bcc_batch_mode | FALSE | TRUE or FALSE (boolean) | 是否启用密送批处理模式（BCC Batch Mode） |
| bcc_batch_size | 200 | None | 使用密送批处理时每一批邮件的数量 |
| dsn | FALSE | TRUE or FALSE (boolean) | 是否启用服务器提示消息|
# 取消自动换行
如果你启用了自动换行（推荐遵守 RFC 822），然后你的邮件中又有一个超长的链接，那么它也会被自动换行， 会导致收件人无法点击该链接。CodeIgniter 允许你禁用部分内容的自动换行，像下面这样:
~~~
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.
~~~
在你不想自动换行的内容前后使用 {unwrap} {/unwrap} 包起来。
# 类参考
**class CI_Email**
**from**($from[, $name = ''[, $return_path = NULL]])
参数:
* $from (string) -- "From" e-mail address
* $name (string) -- "From" display name
* $return_path (string) -- Optional email address to redirect undelivered e-mail to
返回: CI_Email instance (method chaining)
返回类型: CI_Email
设置发件人 email 地址和名称:
~~~
$this->email->from('you@example.com', 'Your Name');
~~~
你还可以设置一个 Return-Path 用于重定向未收到的邮件:
~~~
$this->email->from('you@example.com', 'Your Name', 'returned_emails@example.com');
~~~
**注解**
如果你使用的是 'smtp' 协议，不能使用 Return-Path 。
* * * * *
**reply_to**($replyto[, $name = ''])
参数:
* $replyto (string) -- E-mail address for replies
* $name (string) -- Display name for the reply-to e-mail address
返回: CI_Email instance (method chaining)
返回类型: CI_Email
设置邮件回复地址，如果没有提供这个信息，将会使用 :meth:from 函数中的值。例如:
~~~
$this->email->reply_to('you@example.com', 'Your Name');
~~~
**to**($to)
参数: $to (mixed) -- Comma-delimited string or an array of e-mail addresses
返回: CI_Email instance (method chaining)
返回类型: CI_Email
设置收件人 email 地址，地址可以是单个、一个以逗号分隔的列表或是一个数组:
~~~
$this->email->to('someone@example.com');
~~~
~~~
$this->email->to('one@example.com, two@example.com, three@example.com');
~~~
~~~
$this->email->to(
array('one@example.com', 'two@example.com', 'three@example.com')
);
~~~
* * * * *
**cc**($cc)
参数: $cc (mixed) -- Comma-delimited string or an array of e-mail addresses
返回: CI_Email instance (method chaining)
返回类型: CI_Email
设置抄送（CC）的 email 地址，和 "to" 方法一样，地址可以是单个、一个以逗号分隔的列表或是一个数组。
* * * * *
**bcc**($bcc[, $limit = ''])
参数:
* $bcc (mixed) -- Comma-delimited string or an array of e-mail addresses
* $limit (int) -- Maximum number of e-mails to send per batch
返回: CI_Email instance (method chaining)
返回类型: CI_Email
设置密送（BCC）的 email 地址，和 "to" 方法一样，地址可以是单个、一个以逗号分隔的列表或是一个数组。
如果设置了 $limit 参数，将启用批处理模式，批处理模式可以同时发送一批邮件，每一批不超过设置的 $limit 值。
* * * * *
**subject**($subject)
参数: $subject (string) -- E-mail subject line
返回: CI_Email instance (method chaining)
返回类型: CI_Email
设置 email 主题:
~~~
$this->email->subject('This is my subject');
~~~
* * * * *
**message**($body)
参数: $body (string) -- E-mail message body
返回: CI_Email instance (method chaining)
返回类型: CI_Email
设置 email 正文部分:
~~~
$this->email->message('This is my message');
~~~
* * * * *
**set_alt_message**($str)
参数: $str (string) -- Alternative e-mail message body
返回: CI_Email instance (method chaining)
返回类型: CI_Email
设置可选的 email 正文部分:
~~~
$this->email->set_alt_message('This is the alternative message');
~~~
如果你发送的是 HTML 格式的邮件，可以设置一个可选的正文部分。对于那些设置了不接受 HTML 格式的邮件的人来说， 可以显示一段备选的不包含 HTML 格式的文本。如果你没有设置该参数，CodeIgniter 会自动从 HTML 格式邮件中删掉 HTML 标签。
* * * * *
**set_header**($header, $value)
参数:
* $header (string) -- Header name
* $value (string) -- Header value
返回: CI_Email instance (method chaining)
返回类型: CI_Email
向 email 添加额外的头:
~~~
$this->email->set_header('Header1', 'Value1');
$this->email->set_header('Header2', 'Value2');
~~~
* * * * *
**clear**([$clear_attachments = FALSE])
参数: $clear_attachments (bool) -- Whether or not to clear attachments
返回: CI_Email instance (method chaining)
返回类型: CI_Email
将所有的 email 变量清空，当你在一个循环中发送邮件时，这个方法可以让你在每次发邮件之前将变量重置。
~~~
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();
}
~~~
如果将参数设置为 TRUE ，邮件的附件也会被清空。
~~~
$this->email->clear(TRUE);
~~~
* * * * *
**send**([$auto_clear = TRUE])
参数: $auto_clear (bool) -- Whether to clear message data automatically
返回: TRUE on success, FALSE on failure
返回类型: bool
发送 email ，根据成功或失败返回布尔值 TRUE 或 FALSE ，可以在条件语句中使用:
~~~
if ( ! $this->email->send())
{
// Generate error
}
~~~
如果发送成功，该方法将会自动清除所有的参数。如果不想清除，可以将参数置为 FALSE
~~~
if ($this->email->send(FALSE))
{
// Parameters won't be cleared
}
~~~
**注解**
为了使用 print_debugger() 方法，你必须避免清空 email 的参数。
* * * * *
**attach**($filename[, $disposition = ''[, $newname = NULL[, $mime = '']]])
参数:
* $filename (string) -- File name
* $disposition (string) -- '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
* $newname (string) -- Custom file name to use in the e-mail
* $mime (string) -- MIME type to use (useful for buffered data)
返回: CI_Email instance (method chaining)
返回类型: CI_Email
添加附件，第一个参数为文件的路径。要添加多个附件，可以调用该方法多次。例如:
~~~
$this->email->attach('/path/to/photo1.jpg');
$this->email->attach('/path/to/photo2.jpg');
$this->email->attach('/path/to/photo3.jpg');
~~~
要让附件使用默认的 Content-Disposition（默认为：attachment）将第二个参数留空， 你也可以使用其他的 Content-Disposition
~~~
$this->email->attach('image.jpg', 'inline');
~~~
另外，你也可以使用 URL:
~~~
$this->email->attach('http://example.com/filename.pdf');
~~~
如果你想自定义文件名，可以使用第三个参数:
~~~
$this->email->attach('filename.pdf', 'attachment', 'report.pdf');
~~~
如果你想使用一段字符串来代替物理文件，你可以将第一个参数设置为该字符串，第三个参数设置为文件名， 第四个参数设置为 MIME 类型:
~~~
$this->email->attach($buffer, 'attachment', 'report.pdf', 'application/pdf');
~~~
* * * * *
**attachment_cid**($filename)
参数: $filename (string) -- Existing attachment filename
返回: Attachment Content-ID or FALSE if not found
返回类型: string
设置并返回一个附件的 Content-ID ，可以让你将附件（图片）内联显示到 HTML 正文中去。 第一个参数必须是一个已经添加到附件中的文件名。
~~~
$filename = '/img/photo1.jpg';
$this->email->attach($filename);
foreach ($list as $address)
{
$this->email->to($address);
$cid = $this->email->attachment_cid($filename);
$this->email->message('<img src="cid:'. $cid .'" alt="photo1" />');
$this->email->send();
}
~~~
**注解**
每个 email 的 Content-ID 都必须重新创建，为了保证唯一性。
* * * * *
**print_debugger**([$include = array('headers', 'subject', 'body')])
参数: $include (array) -- Which parts of the message to print out
返回: Formatted debug data
返回类型: string
返回一个包含了所有的服务器信息、email 头部信息、以及 email 信息的字符串，这些信息对调试很有用。
你可以指定只返回消息的哪个部分，有效值有：headers 、 subject 和 body 。
例如:
~~~
// 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'));
~~~
**注解**
默认情况，所有的数据都会被打印出来。
- 空白目录
- 欢迎使用 CodeIgniter
- 安装说明
- 下载CodeIgniter
- 安装说明
- 从老版本升级
- 疑难解答
- CodeIgniter 概览
- 开始
- CodeIgniter 是什么？
- 支持特性
- 应用程序流程图
- 模型-视图-控制器
- 架构目标
- 教程 - 内容提要
- 加载静态内容
- 读取新闻条目
- 创建新闻条目
- 结束语
- 向 CodeIgniter 贡献你的力量
- 编写 CodeIgniter 的文档
- Developer's Certificate of Origin 1.1
- 常规主题
- CodeIgniter URL
- 控制器
- 保留名称
- 视图
- 模型
- 辅助函数
- 使用 CodeIgniter 类库
- 创建类库
- 使用 CodeIgniter 驱动器
- 创建驱动器
- 创建核心系统类
- 创建附属类
- 钩子 - 扩展框架核心
- 自动加载资源
- 公共函数
- 兼容性函数
- URI 路由
- 错误处理
- 网页缓存
- 程序分析
- 以 CLI 方式运行
- 管理你的应用程序
- 处理多环境
- 在视图文件中使用 PHP 替代语法
- 安全
- PHP 开发规范
- 类库参考
- 基准测试类
- 缓存驱动器
- 日历类
- 购物车类
- 配置类
- Email 类
- 加密类
- 加密类（新版）
- 文件上传类
- 表单验证类
- FTP 类
- 图像处理类
- 输入类
- Javascript 类
- 语言类
- 加载器类