Configuring Mail Events and Templates in 1C-Bitrix

After a site migration to a new server, orders stopped reaching the managers. The reason: the new server configuration had no valid SMTP settings, and mail events were configured with a non-existent sender address. Emails went out via sendmail, which silently dropped them; the Bitrix queue showed no errors. Customers submitted requests, managers saw nothing.

Mail events are critical site infrastructure, yet they receive minimal attention during initial setup.

Configuring Mail Events and Templates in 1C-Bitrix

Architecture of Mail Notifications in Bitrix

The Bitrix mail system consists of three layers:

Mail events (Settings → Mail → Mail Events) — event description: type (SALE_NEW_ORDER), list of macros available in templates. This is the event "interface".

Mail event templates (Settings → Mail → Mail Templates) — the concrete implementation: recipient, subject, email body. A single event type can have multiple templates for different sites or conditions.

Mail sending service — configured in Settings → Product Settings → Mail. Supported options: sendmail, mail(), SMTP (with authentication, SSL/TLS). For production, SMTP or an external service (Mailgun, SendGrid, Unisender, DashaMail) is mandatory.

Standard Events and Their Configuration

Bitrix ships with a set of pre-installed events. Key events for an online store:

• SALE_NEW_ORDER — new order (sent to manager and customer)
• SALE_ORDER_PAID — order paid
• SALE_ORDER_CANCELED — order cancelled
• SALE_STATUS_CHANGED — order status changed
• MAIN_USER_REGISTER — user registration
• MAIN_USER_PASS_CHANGED — password change

For each event, configure: sender address (FROM), recipient (TO), subject (SUBJECT), email body. Event macros are available in all fields.

A typical mistake: the FROM field contains an address on a domain different from the sending server's domain. SPF/DKIM fails, emails end up in spam.

SMTP Configuration

Section Settings → Product Settings → Mail → Mail Agent. Specify:

• SMTP host (e.g., smtp.yandex.ru or a corporate server)
• Port: 587 (STARTTLS) or 465 (SSL)
• Mail account login and password
• Encryption type

After configuration — always test via Settings → Diagnostics → Mail Test. If the email does not arrive, check /bitrix/modules/main/lib/mail/ and the SMTP server logs.

Creating Custom Mail Events

For custom notifications (e.g., "manager assigned to deal", "contract is about to expire"), create custom event types via the admin panel or programmatically using CEventType::Add(). Then create templates and trigger sending from code:

CEvent::Send('MY_CUSTOM_EVENT', SITE_ID, [
    'NAME' => $name,
    'EMAIL' => $email,
    'MESSAGE' => $text,
]);

Send Queue and Delays

By default, Bitrix sends emails through a queue — the CAgent::AddAgent() agent calls CMailMessage::SendMessages(). If agents are not running (no cron) or the queue has accumulated — emails are sent with a delay. For critical notifications (order, registration), enable immediate sending in the mail settings.

Timeline