Email 類 · CodeIgniter3.0 中文用戶指南

# Email 類 CodeIgniter 擁有強大的 Email 類支持以下特性： * 多協議：Mail、Sendmail 和 SMTP * SMTP 協議支持 TLS 和 SSL 加密 * 多個收件人 * 抄送（CC）和密送（BCC） * HTML 格式郵件或純文本郵件 * 附件 * 自動換行 * 優先級 * 密送批處理模式（BCC Batch Mode），大郵件列表將被分成小批次密送 * Email 調試工具 [TOC=2,3] ## 使用 Email 類 ### 發送 Email 發送郵件不僅很簡單，而且你可以通過參數或通過配置文件設置發送郵件的不同選項。下面是個簡單的例子，用于演示如何發送郵件。注意：這個例子假設你是在某個?[控制器](http://codeigniter.org.cn/user_guide/general/controllers.html)?里面發送郵件。 ~~~ $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} 包起來。 ## 類參考 classCI_Email >[info] ### 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 。 >[info] ### 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'); ~~~ >[info] ### 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') ); ~~~ >[info] ### cc($cc) 參數: * **$cc**?(mixed) -- Comma-delimited string or an array of e-mail addresses 返回: CI_Email instance (method chaining) 返回類型: CI_Email 設置抄送（CC）的 email 地址，和 "to" 方法一樣，地址可以是單個、一個以逗號分隔的列表或是一個數組。 >[info] ### 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?值。 >[info] ### subject($subject) 參數: * **$subject**?(string) -- E-mail subject line 返回: CI_Email instance (method chaining) 返回類型: CI_Email 設置 email 主題: ~~~ $this->email->subject('This is my subject'); ~~~ >[info] ### message($body) 參數: * **$body**?(string) -- E-mail message body 返回: CI_Email instance (method chaining) 返回類型: CI_Email 設置 email 正文部分: ~~~ $this->email->message('This is my message'); ~~~ >[info] ### 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 標簽。 >[info] ### 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'); ~~~ >[info] ### 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); >[info] ### 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 的參數。 >[info] ### 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](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'); ~~~ >[info] ### 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 都必須重新創建，為了保證唯一性。 >[info] ### 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')); ~~~ > 注解 > 默認情況，所有的數據都會被打印出來。