Skip to content

Magento

Guide for stores running Magento 2 Open Source or Commerce 2.4+. Mailexam connects as an SMTP server through a custom module that routes Magento mail transport and exposes a test endpoint.

What you need

  • A Mailexam account and a project with SMTP credentials.
  • Magento 2.4+ and PHP 8.1+.

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 (the hostname matches the login).

1. Environment variables in env.php

Add to the env section of app/etc/env.php (do not commit passwords to a public repository):

'env' => [
    'MAILEXAM_LOGIN' => 'YOUR_LOGIN',
    'MAILEXAM_PASSWORD' => 'YOUR_PASSWORD',
    'MAILEXAM_PORT' => '587',
    'MAIL_FROM' => 'noreply@example.test',
],

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 app/code/Mailexam/Smtp from the reference repository into your store, then enable it:

bin/magento module:enable Mailexam_Smtp
bin/magento setup:upgrade
bin/magento cache:flush

The module contains:

  • Model/SmtpSender.php — SMTP client with STARTTLS on port 587;
  • Plugin/Mail/TransportPlugin.php — routes Magento transactional mail through Mailexam when credentials are set;
  • Controller/Mail/Test.php — test endpoint POST /mailexam/mail/test.

3. SMTP sender (excerpt)

// app/code/Mailexam/Smtp/Model/SmtpSender.php
public function send(string $to, string $subject, string $body, ?string $from = null): void
{
    if (!$this->config->isConfigured()) {
        throw new \RuntimeException('MAILEXAM_LOGIN and MAILEXAM_PASSWORD must be set');
    }

    $host = $this->config->getHost(); // {login}.mailexam.io
    $port = $this->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-store.test/mailexam/mail/test \
  -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, order confirmations and other Magento emails also go through Mailexam SMTP.

5. Local development and CI

Environment Recommendation
local env section in app/etc/env.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 app/code/Mailexam/Smtp, then run bin/magento setup:upgrade.

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 endpoint returns 404

  • Run bin/magento cache:flush and confirm the module is enabled.

Message not in the dashboard

  • Open inbox for the same Mailexam project.
  • Check var/log/exception.log and the JSON error body from the test endpoint.

See also