Skip to content

Symfony

Guide for applications built with Symfony 6.4 / 7.x. Mailexam connects via Symfony Mailer and an smtp:// DSN in .env.

What you need

  • A Mailexam account and a project with SMTP credentials.
  • A Symfony application (Skeleton or Webapp).

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

If Mailer is not installed yet:

composer require symfony/mailer

In the Symfony Webapp template, the package is usually already included.

2. Environment variables

.env file (or .env.local; do not commit secrets):

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

###> symfony/mailer ###
MAILER_DSN=smtp://${MAILEXAM_LOGIN}:${MAILEXAM_PASSWORD}@${MAILEXAM_LOGIN}.mailexam.io:${MAILEXAM_PORT}
###< symfony/mailer ###

Host in the DSN — YOUR_LOGIN.mailexam.io, login and password — from the email.

Sender address

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

Special characters in password

If the password contains @, :, /, or other DSN characters, URL-encode the password (rawurlencode) or set MAILER_DSN manually in .env.local as a single line.

Alternative ports

MAILEXAM_PORT=587

MAILEXAM_PORT=2525

MAILEXAM_PORT=25

3. Mailer configuration

File config/packages/mailer.yaml (created automatically by Flex):

framework:
    mailer:
        dsn: '%env(MAILER_DSN)%'

No additional transports are required for Mailexam.

4. Sending a test email

Via controller

// src/Controller/MailController.php
namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\Mailer\MailerInterface;
use Symfony\Component\Mime\Email;
use Symfony\Component\Routing\Attribute\Route;

final class MailController extends AbstractController
{
    #[Route('/mail/test', name: 'mail_test', methods: ['POST'])]
    public function test(MailerInterface $mailer): JsonResponse
    {
        $from = $_ENV['MAIL_FROM'] ?? 'noreply@example.test';

        $mailer->send(
            (new Email())
                ->from($from)
                ->to('user@example.test')
                ->subject('Symfony + Mailexam')
                ->text('Mailexam test from Symfony')
        );

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

Start and verify:

symfony server:start
# or: php -S 127.0.0.1:8000 -t public

curl -X POST http://127.0.0.1:8000/mail/test

Via console

php bin/console mailer:test user@example.test --from=noreply@example.test

(the command is available if symfony/mailer is installed and the DSN is configured.)

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

5. Local development and CI

Environment Recommendation
local .env.local with MAILER_DSN
CI Secrets MAILEXAM_LOGIN, MAILEXAM_PASSWORD; build MAILER_DSN in the job

Example for GitLab CI:

variables:
  MAILEXAM_LOGIN: $MAILEXAM_LOGIN
  MAILEXAM_PASSWORD: $MAILEXAM_PASSWORD
  MAILEXAM_PORT: "587"
  MAIL_FROM: "noreply@example.test"
  MAILER_DSN: "smtp://${MAILEXAM_LOGIN}:${MAILEXAM_PASSWORD}@${MAILEXAM_LOGIN}.mailexam.io:587"

For unit tests without real sending, in config/packages/test/mailer.yaml:

framework:
    mailer:
        dsn: 'null://null'

6. Common issues

Authentication failed / connection refused

  • Check MAILER_DSN: host {login}.mailexam.io, login and password — a pair from the email.
  • The login in the DSN user URL must match the host subdomain.

Error due to characters in password

  • Use rawurlencode for the password in the DSN or set the full DSN string manually in .env.local.

Message not in the dashboard

  • Make sure null://null transport is not overridden in test.
  • View the inbox of the same Mailexam project.

Configuration cache

  • After changing .env: php bin/console cache:clear.

See also