Skip to content

Phalcon

Guide for applications built with Phalcon 5.x (PHP). Mailexam connects as SMTP through the phalcon/incubator-mailer package (a wrapper around PHPMailer).

What you need

  • A Mailexam account and a project with SMTP credentials.
  • PHP 8.1+ and the Phalcon extension installed.
  • A Phalcon project (MVC) and Composer.

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 phalcon/incubator-mailer
composer require vlucas/phpdotenv

Verify the extension is loaded:

php -m | grep phalcon

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 public/index.php before creating the application):

Dotenv\Dotenv::createImmutable(BASE_PATH)->safeLoad();

SMTP host: 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

In mailer config: 'encryption' => 'tls'.

MAILEXAM_PORT=2525

'encryption' => 'tls'.

MAILEXAM_PORT=465

'encryption' => 'ssl'.

MAILEXAM_PORT=25

Remove the encryption key or set an empty string.

3. SMTP configuration

app/Services/MailConfig.php:

<?php

declare(strict_types=1);

namespace App\Services;

final class MailConfig
{
    public static function smtp(): array
    {
        $login = getenv('MAILEXAM_LOGIN') ?: '';
        $port = (int) (getenv('MAILEXAM_PORT') ?: 587);
        $from = getenv('MAIL_FROM') ?: 'noreply@example.test';

        $config = [
            'driver'     => 'smtp',
            'host'       => $login . '.mailexam.io',
            'port'       => $port,
            'username'   => $login,
            'password'   => getenv('MAILEXAM_PASSWORD') ?: '',
            'from'       => [
                'email' => $from,
                'name'  => 'Mailexam Test',
            ],
        ];

        if ($port === 465) {
            $config['encryption'] = 'ssl';
        } elseif (in_array($port, [587, 2525], true)) {
            $config['encryption'] = 'tls';
        }

        return $config;
    }
}

4. Sending a test email

app/Controllers/MailController.php:

<?php

declare(strict_types=1);

namespace App\Controllers;

use App\Services\MailConfig;
use Phalcon\Incubator\Mailer\Manager as MailerManager;
use Phalcon\Mvc\Controller;

class MailController extends Controller
{
    public function testAction()
    {
        $this->view->disable();
        $this->response->setContentType('application/json', 'UTF-8');

        $payload = $this->request->getJsonRawBody(true) ?? [];

        $to = $payload['to'] ?? 'user@example.test';
        $subject = $payload['subject'] ?? 'Phalcon + Mailexam';
        $body = $payload['body'] ?? 'Mailexam test from Phalcon';

        $mailer = new MailerManager(MailConfig::smtp());

        $mailer->createMessage()
            ->to($to)
            ->subject($subject)
            ->content($body)
            ->send();

        return $this->response->setJsonContent(['status' => 'ok']);
    }
}

Route in config/routes.php:

<?php

use Phalcon\Mvc\Router;

$router = new Router(false);
$router->setDefaults([
    'namespace'  => 'App\Controllers',
    'controller' => 'index',
    'action'     => 'index',
]);

$router->addPost('/mail/test', [
    'controller' => 'mail',
    'action'     => 'test',
]);

return $router;

Start and verify (built-in PHP server or your vhost):

php -S 127.0.0.1:8080 -t public

curl -X POST http://127.0.0.1:8080/mail/test \
  -H 'Content-Type: application/json' \
  -d '{"to":"user@example.test","subject":"Test","body":"Hello"}'

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

5. Local development and CI

Environment Recommendation
local .env + Dotenv::safeLoad()
CI secrets MAILEXAM_LOGIN, MAILEXAM_PASSWORD in GitLab CI/CD Variables; PHP image with the phalcon extension

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

Class 'Phalcon...' not found

  • Install and enable the Phalcon extension for the same PHP version used in CLI and FPM.

TLS or authentication failed error

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

Port 587

  • Requires 'encryption' => 'tls', not ssl.

Message not in the dashboard

  • View the inbox of the same Mailexam project.
  • Enable PHPMailer debugging in the incubator-mailer config if needed.

See also