דוא"ל ותור שליחה

הליבה שולחת דוא"ל דרך ספריית mail_tpl, שנשענת על PHPMailer 6.9.1 (api/core/addons/PHPMailer). התבניות נערכות בפאנל הניהול, וכל שליחה עוברת באחד משלושה מסלולים: שירות POOLSE, תור במסד הנתונים או שליחה ישירה. בעמוד הזה תראו איך שולחים הודעה, איך נבחר המסלול, איך מפעילים תור ואילו מלכודות יש.

תבניות: CRM_mail_tpl#

תבניות ההודעות נשמרות בטבלת CRM_mail_tpl ונערכות בפאנל {admin}/MailTpl:

הגוף, הנושא ו-fromName עוברים עיבוד Smarty (FILES::string_template) עם המשתנים שהגדרתם ב-set_var. בתבנית כותבים {$name}, {if} ו-{foreach} כמו בכל תבנית אתר (ראו תבניות Smarty).

אם הפרמטר mail_tpl ב-CRM_params מכיל נתיב של תבנית HTML, הגוף הסופי עובר דרכה כעטיפה. בעטיפה זמינים {$content} (הגוף שעובד), {$to} וכל המשתנים שהוגדרו ב-set_var. ראו פרמטרים ושפות לעריכת פרמטרים.

שליחת הודעה#

$this->load->library("mail_tpl");

$m = new mail_tpl("order_confirm");              // sysName של שורה ב-CRM_mail_tpl
$m->set_to("client@example.co.il");              // אפשר לקרוא כמה פעמים; clear_to() מאפס
$m->set_var("name", $order["client_name"]);      // {$name} בתבנית
$m->set_var("items", $order["items"]);           // {foreach $items as $it} ... {/foreach}
$m->priority = 1;                                // עדיפות בתור (נמוך = קודם)
$m->attach_url = [["url" => $pdf_path, "name" => "invoice.pdf"]];
$m->reply = "sales@example.co.il";
$m->replyName = "מכירות";
$ok = $m->send();                                // true אם נשלח או נכנס לתור

הערך שחוזר מ-send() הוא true כשההודעה נמסרה או נכנסה לתור. ה-constructor לא בודק שהתבנית קיימת: עבור sysName לא מוכר תקבלו אזהרות PHP והודעה ריקה. אם השם מגיע מקלט דינמי, ודאו קודם עם mail_tpl::get_tpl_data($sysName), שמחזיר false כשאין שורה.

מאפיינים ציבוריים#

מתודות#

הודעה חופשית: mail_string#

כשאין שורה בטבלה, mail_string מקבלת את הגוף ישירות:

$s = new mail_string("<p>שלום {\$name}</p>");
$s->subject = "עדכון";
$s->set_var("name", $user["name"]);
$s->set_to($user["email"]);
$s->send();

mail_string יורשת את כל המתודות של mail_tpl, והגוף שלה עובר גם הוא דרך Smarty. לכן לעולם אל תשרשרו קלט משתמש לתוך המחרוזת: העבירו אותו דרך set_var, כך שהוא ערך ולא קוד תבנית.

מסלולי השליחה#

send() בוחרת מסלול לפי הסדר הבא:

1. POOLSE. אם יש נמען אחד, אין cc ו-bcc, הפרמטר poolse_mail אינו "0", התבנית לא מופיעה ברשימת poolse_mail_exclude, ו-poolse_client::active() נכון: ההודעה נשלחת ל-POOLSE דרך poolse_client::transactional. אם הצליח, נרשמת שורת לוג בתור (is_sent = 1) ונגמר.
2. תור. אם CONFIG::$mail_queue פעיל ו-$skip_queue כבוי: ההודעה נכנסת ל-CRM_emails_queue ונשלחת מאוחר יותר על ידי משימת cron.
3. ישיר. אחרת: PHPMailer::send() מיידי, ואחריו שורת לוג בתור.

אם POOLSE נכשל או לא חל (קובץ שלא מתאים, שירות שלא זמין), המערכת ממשיכה למסלול 2 או 3 ולא מאבדת את ההודעה.

פרטים על מסלול POOLSE:

• הכתובת שולחת מהדומיין המאומת של חשבון POOLSE. הערך $from של ההודעה הופך ל-Reply-To (או $reply אם הוגדר).
• קבצים מצורפים עוברים רק מנתיב מקומי, עד 5 קבצים, עד 2MB לקובץ ו-3MB בסך הכל, ובסיומות מרשימה מותרת (pdf, ics, csv, txt, תמונות, מסמכי Office ועוד). קובץ שלא עומד בכך, או כתובת URL מרוחקת, מעביר את ההודעה כולה למסלול הרגיל עם הקובץ.
• $ical עובר כחלק calendar של ה-API.
• לכבות POOLSE לאתר: poolse_mail = 0 ב-CRM_params. להחזיק תבנית אחת מחוץ ל-POOLSE: poolse_mail_exclude עם רשימת sysName מופרדת בפסיק.

הגדרות SMTP#

ללא הגדרה, PHPMailer שולח עם mail() של PHP. להגדרת SMTP מוסיפים ל-CONFIG_USER בקובץ ההגדרות של האתר (ראו הגדרות):

static $mail_is_smtp      = true;            // חייב להיות true בדיוק (===)
static $mail_smtp_host    = "smtp.example.com";
static $mail_smtp_port    = 587;
static $mail_smtp_auth    = true;
static $mail_smtp_username = "mailer@example.com";
static $mail_smtp_password = "";             // מהכספת או ממשתנה סביבה, לא בקוד
static $mail_smtp_secure  = "tls";           // "tls" או "ssl"
static $mail_queue        = false;           // true = שליחה דרך התור

הליבה לא מצהירה על המפתחות האלה. אתר שמשתמש בדוא"ל חייב להצהיר עליהם, גם כשהם false, כי קריאה למאפיין סטטי לא מוצהר היא שגיאה קטלנית ב-PHP 8.

התור: CRM_emails_queue#

MISC::add_mail_to_queue($mail, $priority = 1, $mail_tpl = "", $is_sent = false, $pid = false) כותב לשם. עם $is_sent = true השורה היא רשומת לוג בלבד (log = 1, send_date עכשיו).

הפעלת התור#

התור נשלח על ידי Tools::cron_emails_queue, ואינו נרשם אוטומטית. כשמפעילים CONFIG::$mail_queue, יוצרים משימה ב-{admin}/cron_manager עם url = system/Tools/cron_emails_queue ותדירות של כל דקה או שתיים (ראו משימות מתוזמנות).

בכל הרצה:

1. בתוך טרנזקציה: בוחרת עד 250 שורות עם is_sent = 0 ו-send_date <= NOW(), בסדר priority ואז send_date, עם FOR UPDATE.
2. מסמנת אותן כנשלחות.
3. לכל שורה: unserialize וקריאה ל-send(). הצלחה נרשמת ב-log, כישלון מסומן error ולא ינוסה שוב.
4. מוחקת שורות עם is_sent = 1 שגילן מעל 24 שעות.

poolse_client#

libraries/poolse_client.php הוא לקוח ל-POOLSE, שירות דוא"ל, קמפיינים ואוטומציות של המרקט. כל המתודות סטטיות, לא זורקות חריגות, ומחזירות false או ["error" => ...] בכישלון, כדי שתקלה בשירות לא תפיל את האתר.

$this->load->library("poolse_client");

if (poolse_client::active()) {
    poolse_client::subscribe(["email" => $email, "first_name" => $name, "list_ids" => [1]]);
    poolse_client::event($email, "purchase_completed", ["order_total" => 250]);
}

MISC::email: הפונקציה הישנה#

MISC::email($to, $from, $subj, $msg, $bcc = "") שולחת עם mail() של PHP ובונה את הכותרות בשרשור מחרוזות. היא לא מנקה שורות חדשות מהערכים, ולכן ערך כמו $from שמגיע מקלט משתמש מאפשר הזרקת כותרות. העדיפו תמיד mail_tpl, ואם אתם קוראים לפונקציה, ודאו שאף ערך בה לא מכיל \r או \n.

צ'קליסט לאתר חדש#

• שורת תבנית ב-CRM_mail_tpl לכל הודעה, עם sysName יציב.
• from מדומיין שיש לו SPF, DKIM ו-DMARC, או POOLSE שמטפל בזה.
• החלטה: POOLSE, תור או ישיר. אם תור: משימת cron לכל דקה והגנה על ה-URL שלה.
• סיסמת SMTP מחוץ לקוד.
• בדיקה אחת עם כתובת שלכם לפני כל שימוש חדש.

ראו גם#

• משימות מתוזמנות
• פונקציות עזר (MISC)
• פרמטרים ושפות
• הגדרות
• שירותי המרקט
• הקשחה