Skip to content

Yii

Guide for applications built with Yii 2 (2.0.43+). Mailexam connects as an SMTP server through the mailer component and the yii2-symfonymailer extension.

What you need

  • A Mailexam account and a project with SMTP credentials.
  • Yii 2 (Basic or Advanced template).

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. Dependencies

composer require yiisoft/yii2-symfonymailer
composer require vlucas/phpdotenv  # for .env in local development

composer.json should include yiisoft/yii2-symfonymailer and, if needed, vlucas/phpdotenv.

2. Environment variables

.env file in the project root (add to .gitignore):

MAILEXAM_LOGIN=YOUR_LOGIN
MAILEXAM_PASSWORD=YOUR_PASSWORD
MAILEXAM_PORT=587
MAIL_FROM=noreply@example.test

Load .env at startup (for example, in web/index.php and yii before creating the application):

Dotenv\Dotenv::createImmutable(__DIR__ . '/..')->safeLoad();

Host in configuration: YOUR_LOGIN.mailexam.io.

Sender address

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

Alternative ports

MAILEXAM_PORT=587

MAILEXAM_PORT=2525

MAILEXAM_PORT=25

3. mailer component

Fragment of config/web.php (or shared config/main.php):

<?php

$login = getenv('MAILEXAM_LOGIN') ?: '';
$port = (int) (getenv('MAILEXAM_PORT') ?: 587);

return [
    // ...
    'components' => [
        'mailer' => [
            'class' => \yii\symfonymailer\Mailer::class,
            'useFileTransport' => false,
            'transport' => [
                'scheme' => 'smtp',
                'host' => $login . '.mailexam.io',
                'username' => $login,
                'password' => getenv('MAILEXAM_PASSWORD') ?: '',
                'port' => $port,
            ],
        ],
    ],
];

For the Advanced Template, add the same settings to common/config/main-local.php.

Make sure useFileTransport is set to false; otherwise messages are saved to files instead of being sent via SMTP.

4. Sending a test email

Via console

// commands/MailController.php
namespace app\commands;

use Yii;
use yii\console\Controller;

class MailController extends Controller
{
    public function actionTest(): int
    {
        $from = getenv('MAIL_FROM') ?: 'noreply@example.test';

        $sent = Yii::$app->mailer->compose()
            ->setFrom([$from => 'Mailexam Test'])
            ->setTo('user@example.test')
            ->setSubject('Yii + Mailexam')
            ->setTextBody('Mailexam test from Yii')
            ->send();

        $this->stdout($sent ? "ok\n" : "error\n");
        return $sent ? self::EXIT_CODE_NORMAL : self::EXIT_CODE_ERROR;
    }
}

php yii mail/test

Via HTTP (controller)

// controllers/MailController.php
namespace app\controllers;

use Yii;
use yii\web\Controller;
use yii\web\Response;

class MailController extends Controller
{
    public function actionTest(): array
    {
        Yii::$app->response->format = Response::FORMAT_JSON;

        $from = getenv('MAIL_FROM') ?: 'noreply@example.test';

        Yii::$app->mailer->compose()
            ->setFrom([$from => 'Mailexam Test'])
            ->setTo('user@example.test')
            ->setSubject('Yii + Mailexam')
            ->setTextBody('Mailexam test from Yii')
            ->send();

        return ['status' => 'ok'];
    }
}

Add a rule in urlManager and open the route in a browser or call it with curl.

The message will appear in the Mailexam dashboard → your project → inbox.

5. Local development and CI

Environment Recommendation
local .env or *-local.php with Mailexam credentials
CI Variables MAILEXAM_LOGIN, MAILEXAM_PASSWORD in pipeline secrets

Example for GitLab CI:

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

After sending a message in the pipeline, verify delivery via the Mailexam API.

6. Common issues

Message not sent, files in runtime/mail

  • Check useFileTransport => false in the mailer configuration.

TLS or connection error

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

Environment variables are empty

  • Call Dotenv::createImmutable(...)->safeLoad() before new yii\web\Application($config).
  • In production, set variables in the PHP-FPM / container environment.

Message not in the dashboard

  • View the inbox of the same Mailexam project.
  • Enable debug: Yii::debug(Yii::$app->mailer->transport) if needed.

See also