Skip to content

1C-Bitrix

Guide for sites running 1C-Bitrix: Site Management 20+ (D7). Mailexam connects as an SMTP server through the mailexam.smtp module and the OnBeforePhpMailerInit event handler.

What you need

  • A Mailexam account and a project with SMTP credentials.
  • 1C-Bitrix 20+ and PHP 8.0+.

Copy from the welcome email (or dashboard) for your project:

  • YOUR_LOGIN — SMTP login (for example, xxxxx);
  • YOUR_PASSWORD — SMTP password (a unique pair with the login);
  • host — YOUR_LOGIN.mailexam.io (matches the login).

1. Variables in .settings.php

Add an environment section to bitrix/.settings.php (do not commit passwords to a public repository):

'environment' => [
    'value' => [
        'MAILEXAM_LOGIN' => 'YOUR_LOGIN',
        'MAILEXAM_PASSWORD' => 'YOUR_PASSWORD',
        'MAILEXAM_PORT' => '587',
        'MAIL_FROM' => 'noreply@example.test',
    ],
    'readonly' => true,
],

SMTP host in code: YOUR_LOGIN.mailexam.io.

Sender address

MAIL_FROM can be any test address — the message still goes to Mailexam, not to a real recipient.

Alternative ports

'MAILEXAM_PORT' => '587',

The module uses STARTTLS for ports 587 and 2525.

'MAILEXAM_PORT' => '2525',

'MAILEXAM_PORT' => '25',

Plain SMTP without STARTTLS.

2. Install the module

Copy local/modules/mailexam.smtp and local/tools/mailexam from the reference repository into your site, then install the module:

  • in the admin panel: Marketplace → Installed solutions;
  • or via CLI (if available on your host).

The module contains:

  • lib/smtpsender.php — SMTP client with STARTTLS on port 587;
  • lib/eventhandler.php — PHPMailer configuration via OnBeforePhpMailerInit;
  • local/tools/mailexam/mail_test.php — test endpoint.

3. SMTP sender (excerpt)

// local/modules/mailexam.smtp/lib/smtpsender.php
public function send(string $to, string $subject, string $body, ?string $from = null): void
{
    if (!Config::isConfigured()) {
        throw new \RuntimeException('MAILEXAM_LOGIN and MAILEXAM_PASSWORD must be set');
    }

    $host = Config::getHost(); // {login}.mailexam.io
    $port = Config::getPort();

    if (in_array($port, [587, 2525], true)) {
        $this->sendWithStartTls(/* ... */);
        return;
    }

    $this->sendPlain(/* ... */);
}

See the full module in the GitHub repository.

4. Test send

curl -X POST https://your-site.test/local/tools/mailexam/mail_test.php \
  -H 'Content-Type: application/json' \
  -d '{"to":"user@example.test","subject":"Test","body":"Hello"}'

The message appears in the Mailexam dashboard → your project → inbox.

When MAILEXAM_LOGIN and MAILEXAM_PASSWORD are set, Bitrix system mail (registration, forms, notifications) also goes through Mailexam SMTP.

5. Local development and CI

Environment Recommendation
local environment section in bitrix/.settings.php
CI secrets MAILEXAM_LOGIN, MAILEXAM_PASSWORD in pipeline variables

Example for .gitlab-ci.yml:

variables:
  MAILEXAM_LOGIN: $MAILEXAM_LOGIN
  MAILEXAM_PASSWORD: $MAILEXAM_PASSWORD
  MAILEXAM_PORT: "587"
  MAIL_FROM: "noreply@example.test"

After an integration test, verify delivery via the Mailexam API.

6. Common issues

Module not found after copy

  • Path must be local/modules/mailexam.smtp, then install the module in the admin panel.

TLS or authentication failed

  • Host must be {login}.mailexam.io, username the same login from the email.
  • Login and password are a pair from one project welcome email.

Test script returns 404

  • Check the URL /local/tools/mailexam/mail_test.php.
  • Ensure the local/tools directory is served by the web server.

Message not in the dashboard

  • Open inbox for the same Mailexam project.
  • Check the JSON error body from mail_test.php and PHP logs.

See also