Email 类

CodeIgniter 拥有强大的 Email 类支持以下特性:

  • 多协议:Mail、Sendmail 和 SMTP
  • SMTP 协议支持 TLS 和 SSL 加密
  • 多个收件人
  • 抄送(CC)和密送(BCC)
  • HTML 格式邮件 或 纯文本邮件
  • 附件
  • 自动换行
  • 优先级
  • 密送批处理模式(BCC Batch Mode),大邮件列表将被分成小批次密送
  • Email 调试工具

使用 Email 类

发送 Email

发送邮件不仅很简单,而且你可以通过参数或通过配置文件设置发送邮件的不同选项。

下面是个简单的例子,用于演示如何发送邮件。注意:这个例子假设你是在某个 控制器里面发送邮件。

  1. $this->load->library('email');
  2.  
  3. $this->email->from('your@example.com', 'Your Name');
  4. $this->email->to('someone@example.com');
  5. $this->email->cc('another@another-example.com');
  6. $this->email->bcc('them@their-example.com');
  7.  
  8. $this->email->subject('Email Test');
  9. $this->email->message('Testing the email class.');
  10.  
  11. $this->email->send();

设置 Email 参数

有 21 种不同的参数可以用来对你发送的邮件进行配置。你可以像下面这样手工设置它们,或者通过配置文件自动加载,见下文:

通过向邮件初始化函数传递一个包含参数的数组来设置参数,下面是个如何设置参数的例子:

  1. $config['protocol'] = 'sendmail';
  2. $config['mailpath'] = '/usr/sbin/sendmail';
  3. $config['charset'] = 'iso-8859-1';
  4. $config['wordwrap'] = TRUE;
  5.  
  6. $this->email->initialize($config);

注解

如果你不设置,大多数参数将使用默认值。

在配置文件中设置 Email 参数

如果你不喜欢使用上面的方法来设置参数,你可以将它们放到配置文件中。你只需要简单的创建一个新文件email.php ,将 $config 数组放到该文件,然后保存到 config/email.php ,这样它将会自动被加载。如果你使用配置文件的方式来设置参数,你就不需要使用 $this->email->initialize() 方法了。

Email 参数

下表为发送邮件时所有可用的参数。

参数默认值选项描述
useragentCodeIgniterNone用户代理(user agent)
protocolmailmail, sendmail, or smtp邮件发送协议
mailpath/usr/sbin/sendmailNone服务器上 Sendmail 的实际路径
smtp_hostNo DefaultNoneSMTP 服务器地址
smtp_userNo DefaultNoneSMTP 用户名
smtp_passNo DefaultNoneSMTP 密码
smtp_port25NoneSMTP 端口
smtp_timeout5NoneSMTP 超时时间(单位:秒)
smtp_keepaliveFALSETRUE or FALSE (boolean)是否启用 SMTP 持久连接
smtp_cryptoNo Defaulttls or sslSMTP 加密方式
wordwrapTRUETRUE or FALSE (boolean)是否启用自动换行
wrapchars76 自动换行时每行的最大字符数
mailtypetexttext or html邮件类型。如果发送的是 HTML 邮件,必须是一个完整的网页,确保网页中没有使用相对路径的链接和图片地址,它们在邮件中不能正确显示。
charset$config['charset'] 字符集(utf-8, iso-8859-1 等)
validateFALSETRUE or FALSE (boolean)是否验证邮件地址
priority31, 2, 3, 4, 5Email 优先级(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_modeFALSETRUE or FALSE (boolean)是否启用密送批处理模式(BCC Batch Mode)
bcc_batch_size200None使用密送批处理时每一批邮件的数量
dsnFALSETRUE or FALSE (boolean)是否启用服务器提示消息

取消自动换行

如果你启用了自动换行(推荐遵守 RFC 822),然后你的邮件中又有一个超长的链接,那么它也会被自动换行,会导致收件人无法点击该链接。CodeIgniter 允许你禁用部分内容的自动换行,像下面这样:

  1. The text of your email that
  2. gets wrapped normally.
  3.  
  4. {unwrap}http://example.com/a_long_link_that_should_not_be_wrapped.html{/unwrap}
  5.  
  6. More text that will be
  7. wrapped normally.

在你不想自动换行的内容前后使用 {unwrap} {/unwrap} 包起来。

类参考

  • _class _CI_Email
    • from($from[, $name = ''[, $return_path = NULL]])

参数:

  1. - **$from** (_string_) -- "From" e-mail address
  2. - **$name** (_string_) -- "From" display name
  3. - **$return_path** (_string_) -- Optional email address to redirect undelivered e-mail to返回:

CI_Email instance (method chaining)返回类型:CI_Email

设置发件人 email 地址和名称:

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

你还可以设置一个 Return-Path 用于重定向未收到的邮件:

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

注解

如果你使用的是 'smtp' 协议,不能使用 Return-Path 。

  • replyto($replyto[, $name = ''_])

参数:

  1. - **$replyto** (_string_) -- E-mail address for replies
  2. - **$name** (_string_) -- Display name for the reply-to e-mail address返回:

CI_Email instance (method chaining)返回类型:CI_Email

设置邮件回复地址,如果没有提供这个信息,将会使用 :meth:from 函数中的值。例如:

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

参数:

  1. - **$to** (_mixed_) -- Comma-delimited string or an array of e-mail addresses返回:

CI_Email instance (method chaining)返回类型:CI_Email

设置收件人 email 地址,地址可以是单个、一个以逗号分隔的列表或是一个数组:

  1. $this->email->to('someone@example.com');
  1. $this->email->to('one@example.com, two@example.com, three@example.com');
  1. $this->email->to(
  2. array('one@example.com', 'two@example.com', 'three@example.com')
  3. );
  • cc($cc)

参数:

  1. - **$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 = ''])

参数:

  1. - **$bcc** (_mixed_) -- Comma-delimited string or an array of e-mail addresses
  2. - **$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)

参数:

  1. - **$subject** (_string_) -- E-mail subject line返回:

CI_Email instance (method chaining)返回类型:CI_Email

设置 email 主题:

  1. $this->email->subject('This is my subject');
  • message($body)

参数:

  1. - **$body** (_string_) -- E-mail message body返回:

CI_Email instance (method chaining)返回类型:CI_Email

设置 email 正文部分:

  1. $this->email->message('This is my message');
  • setalt_message($str_)

参数:

  1. - **$str** (_string_) -- Alternative e-mail message body返回:

CI_Email instance (method chaining)返回类型:CI_Email

设置可选的 email 正文部分:

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

如果你发送的是 HTML 格式的邮件,可以设置一个可选的正文部分。对于那些设置了不接受 HTML 格式的邮件的人来说,可以显示一段备选的不包含 HTML 格式的文本。如果你没有设置该参数,CodeIgniter 会自动从 HTML 格式邮件中删掉 HTML 标签。

  • setheader($header, $value_)

参数:

  1. - **$header** (_string_) -- Header name
  2. - **$value** (_string_) -- Header value返回:

CI_Email instance (method chaining)返回类型:CI_Email

向 email 添加额外的头:

  1. $this->email->set_header('Header1', 'Value1');
  2. $this->email->set_header('Header2', 'Value2');
  • clear([$clear_attachments = FALSE])

参数:

  1. - **$clear_attachments** (_bool_) -- Whether or not to clear attachments返回:

CI_Email instance (method chaining)返回类型:CI_Email

将所有的 email 变量清空,当你在一个循环中发送邮件时,这个方法可以让你在每次发邮件之前将变量重置。

  1. foreach ($list as $name => $address)
  2. {
  3. $this->email->clear();
  4.  
  5. $this->email->to($address);
  6. $this->email->from('your@example.com');
  7. $this->email->subject('Here is your info '.$name);
  8. $this->email->message('Hi '.$name.' Here is the info you requested.');
  9. $this->email->send();
  10. }

如果将参数设置为 TRUE ,邮件的附件也会被清空。

$this->email->clear(TRUE);
  • send([$auto_clear = TRUE])

参数:

  1. - **$auto_clear** (_bool_) -- Whether to clear message data automatically返回:

TRUE on success, FALSE on failure返回类型:bool

发送 email ,根据成功或失败返回布尔值 TRUE 或 FALSE ,可以在条件语句中使用:

  1. if ( ! $this->email->send())
  2. {
  3. // Generate error
  4. }

如果发送成功,该方法将会自动清除所有的参数。如果不想清除,可以将参数置为 FALSE

  1. if ($this->email->send(FALSE))
  2. {
  3. // Parameters won't be cleared
  4. }

注解

为了使用 print_debugger() 方法,你必须避免清空 email 的参数。

  • attach($filename[, $disposition = ''[, $newname = NULL[, $mime = '']]])

参数:

  1. - **$filename** (_string_) -- File name
  2. - **$disposition** (_string_) -- 'disposition' of the attachment. Mostemail clients make their own decision regardless of the MIMEspecification used here. [https://www.iana.org/assignments/cont-disp/cont-disp.xhtml](https://www.iana.org/assignments/cont-disp/cont-disp.xhtml)
  3. - **$newname** (_string_) -- Custom file name to use in the e-mail
  4. - **$mime** (_string_) -- MIME type to use (useful for buffered data)返回:

CI_Email instance (method chaining)返回类型:CI_Email

添加附件,第一个参数为文件的路径。要添加多个附件,可以调用该方法多次。例如:

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

要让附件使用默认的 Content-Disposition(默认为:attachment)将第二个参数留空,你也可以使用其他的 Content-Disposition

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

另外,你也可以使用 URL:

  1. $this->email->attach('http://example.com/filename.pdf');

如果你想自定义文件名,可以使用第三个参数:

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

如果你想使用一段字符串来代替物理文件,你可以将第一个参数设置为该字符串,第三个参数设置为文件名,第四个参数设置为 MIME 类型:

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

参数:

  1. - **$filename** (_string_) -- Existing attachment filename返回:

Attachment Content-ID or FALSE if not found返回类型:string

设置并返回一个附件的 Content-ID ,可以让你将附件(图片)内联显示到 HTML 正文中去。第一个参数必须是一个已经添加到附件中的文件名。

  1. $filename = '/img/photo1.jpg';
  2. $this->email->attach($filename);
  3. foreach ($list as $address)
  4. {
  5. $this->email->to($address);
  6. $cid = $this->email->attachment_cid($filename);
  7. $this->email->message('<img src="cid:'. $cid .'" alt="photo1" />');
  8. $this->email->send();
  9. }

注解

每个 email 的 Content-ID 都必须重新创建,为了保证唯一性。

  • printdebugger([$include = array('headers', 'subject', 'body')_])

参数:

  1. - **$include** (_array_) -- Which parts of the message to print out返回:

Formatted debug data返回类型:string

返回一个包含了所有的服务器信息、email 头部信息、以及 email 信息的字符串,这些信息对调试很有用。

你可以指定只返回消息的哪个部分,有效值有:headerssubjectbody

例如:

  1. // You need to pass FALSE while sending in order for the email data
  2. // to not be cleared - if that happens, print_debugger() would have
  3. // nothing to output.
  4. $this->email->send(FALSE);
  5.  
  6. // Will only print the email headers, excluding the message subject and body
  7. $this->email->print_debugger(array('headers'));

注解

默认情况,所有的数据都会被打印出来。