Symfony: Polish Newsletter Imports with AI Email Verification and Manual Triage
A newsletter import can look successful while quietly making the mailing list worse. Obvious typos are easy to remove. The difficult addresses are plausible: a domain exists, mail infrastructure responds, and delivery risk remains uncertain.
This Symfony application turns a CSV into three explicit outcomes: cleaned contacts, rejected contacts, and a manual review queue. Email verification supplies evidence; your application decides what that evidence permits. An outage must never turn an unchecked address into an approved subscriber.
Get access and configure the service token
- Register an account, or sign in.
- Open the Email Validator service and plan page, choose an available Free, Plus, or Pro plan, and complete activation.
- Open the official documentation. Find the Service token panel and copy the service-scoped token.
- Store it in your project's environment configuration. Regenerating this token revokes the previous active token, so rotation requires coordinating application updates.
This service requires a token. The exact request is GET https://ai.mihajlo.mk/api/email-validator/v1/check-email, with token and email query parameters. A minimal request looks like this; substitute the placeholder only in a secure environment:
curl --get 'https://ai.mihajlo.mk/api/email-validator/v1/check-email' \
--data-urlencode 'token=YOUR_SERVICE_TOKEN' \
--data-urlencode '[email protected]'
The response supplies status, score, recommendation, checks, and quota data. Do not infer undocumented status values, score scales, check names, or quota semantics. Consult the documentation before enabling automatic acceptance.
Create a small, bounded Symfony importer
Use PHP 8.3 or later, Composer, and Symfony 7.4. This implementation runs synchronously through Console: a reasonable trade-off for bounded administrative imports. Messenger would add operational overhead without improving this particular workflow.
composer create-project symfony/skeleton:"7.4.*" newsletter-import
cd newsletter-import
composer require symfony/http-client:"7.4.*" symfony/monolog-bundle:"^3.10"
composer require --dev phpunit/phpunit:"^11.5"
Before building the feature, add the credential to .env.local:
EMAIL_VALIDATOR_TOKEN=YOUR_SERVICE_TOKEN
Keep that file out of version control. Production should inject the same variable through its secret manager. The project adds src/EmailVerifier.php, src/Command/ImportContacts.php, config/email-policy.json, and tests/EmailVerifierTest.php.
Create the policy file with {"accept":[],"reject":[]}. This deliberately starts in review mode. Each approved rule must contain an exact status, recommendation, and checks value, plus numeric min and max score bounds. Populate these from verified documentation and representative responses; the bounds use the service's actual score scale.
Exact check matching is conservative: new or changed evidence returns to review. Quota data must also be present and non-null before an automatic decision is possible. We retain its full value for review without inventing a remaining-quota field.
Add these entries beneath the existing services: key in config/services.yaml:
App\EmailVerifier:
arguments:
$token: '%env(EMAIL_VALIDATOR_TOKEN)%'
$policyPath: '%kernel.project_dir%/config/email-policy.json'
App\Command\ImportContacts:
arguments:
$projectDir: '%kernel.project_dir%'
Keep the HTTP boundary conservative
The verifier checks syntax locally, then uses Symfony's injected HttpClientInterface. A three-second inactivity timeout covers stalled connections and reads; an eight-second total duration bounds each attempt. Only transport failures and selected temporary HTTP failures receive retries.
<?php
// src/EmailVerifier.php
namespace App;
use Psr\Log\LoggerInterface;
use Symfony\Contracts\HttpClient\Exception\TransportExceptionInterface;
use Symfony\Contracts\HttpClient\HttpClientInterface;
final class EmailVerifier
{
private array $policy;
private ?string $blocked = null;
public function __construct(
private HttpClientInterface $http,
private LoggerInterface $logger,
private string $token,
string $policyPath,
) {
$this->policy = json_decode(
file_get_contents($policyPath), true, 512, JSON_THROW_ON_ERROR
);
}
public function fingerprint(): string
{
return hash('sha256', json_encode($this->policy, JSON_THROW_ON_ERROR));
}
private function result(string $decision, string $reason, array $evidence = []): array
{
return compact('decision', 'reason', 'evidence');
}
public function check(string $email): array
{
if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {
return $this->result('reject', 'local_syntax');
}
if ($this->blocked !== null) {
return $this->result('review', $this->blocked);
}
for ($attempt = 0; $attempt < 3; ++$attempt) {
$status = 0;
$retryAfter = null;
try {
$response = $this->http->request('GET',
'https://ai.mihajlo.mk/api/email-validator/v1/check-email', [
'query' => ['token' => $this->token, 'email' => $email],
'timeout' => 3,
'max_duration' => 8,
'max_redirects' => 0,
]);
$status = $response->getStatusCode();
if ($status === 200) {
try {
$data = json_decode(
$response->getContent(false), true, 512,
JSON_THROW_ON_ERROR
);
} catch (\JsonException) {
return $this->result('review', 'invalid_json');
}
return $this->map($data);
}
$retryAfter = $response->getHeaders(false)['retry-after'][0] ?? null;
$response->cancel();
} catch (TransportExceptionInterface) {
// Never log the exception: it may contain the credential-bearing URL.
}
$this->logger->warning('email_verification_failed', [
'http_status' => $status,
'attempt' => $attempt + 1,
]);
$temporary = in_array($status, [0, 429, 502, 503, 504], true);
$delay = 0.1 * (2 ** $attempt);
if ($status === 429) {
// Retry only a short, explicit integer Retry-After.
if (!is_string($retryAfter) || !ctype_digit($retryAfter)
|| (int) $retryAfter > 2) {
$temporary = false;
} else {
$delay = (float) $retryAfter;
}
}
if (!$temporary || $attempt === 2) {
$reason = $status === 429 ? 'rate_limited' : 'verification_unavailable';
if (in_array($status, [0, 401, 403, 429, 502, 503, 504], true)) {
$this->blocked = $reason;
}
return $this->result('review', $reason);
}
usleep((int) ($delay * 1_000_000) + random_int(0, 50_000));
}
throw new \LogicException('Unreachable');
}
private function map(mixed $data): array
{
if (!is_array($data)) {
return $this->result('review', 'invalid_contract');
}
$evidence = array_intersect_key($data, array_flip([
'status', 'score', 'recommendation', 'checks', 'quota',
]));
if (!is_string($data['status'] ?? null)
|| !is_string($data['recommendation'] ?? null)
|| !(is_int($data['score'] ?? null) || is_float($data['score'] ?? null))
|| !is_finite((float) $data['score'])
|| !is_array($data['checks'] ?? null)
|| !isset($data['quota'])) {
return $this->result('review', 'invalid_contract', $evidence);
}
// Reject wins if configuration accidentally contains overlapping rules.
foreach (['reject', 'accept'] as $decision) {
foreach ($this->policy[$decision] ?? [] as $rule) {
if (($rule['status'] ?? null) === $data['status']
&& ($rule['recommendation'] ?? null) === $data['recommendation']
&& ($rule['checks'] ?? null) === $data['checks']
&& is_numeric($rule['min'] ?? null)
&& is_numeric($rule['max'] ?? null)
&& $data['score'] >= $rule['min']
&& $data['score'] <= $rule['max']) {
return $this->result($decision, 'policy_match', $evidence);
}
}
}
return $this->result('review', 'uncertain', $evidence);
}
}
Authentication failures are never retried. A rate-limit response without a short usable delay stops further remote calls for this process; remaining contacts enter review. Missing or unexpectedly typed response values also enter review. If the service documents another quota representation, adapt this single boundary and its tests.
Publish complete import artifacts
The input header is exactly email,consent_reference. A consent reference points to your existing permission record; its presence alone does not establish consent. Verification never grants permission to send.
The command limits input to 1,000 contacts and two megabytes, deduplicates exact addresses, and publishes three JSONL files by renaming a completed staging directory. JSONL also avoids encouraging staff to open untrusted email values directly as spreadsheet formulas.
<?php
// src/Command/ImportContacts.php
namespace App\Command;
use App\EmailVerifier;
use Symfony\Component\Console\Attribute\AsCommand;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputArgument;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;
#[AsCommand(name: 'app:import-contacts')]
final class ImportContacts extends Command
{
public function __construct(
private EmailVerifier $verifier,
private string $projectDir,
) {
parent::__construct();
}
protected function configure(): void
{
$this->addArgument('csv', InputArgument::REQUIRED);
}
protected function execute(InputInterface $input, OutputInterface $output): int
{
$base = $this->projectDir.'/var/imports';
if (!is_dir($base) && !mkdir($base, 0700, true)) {
throw new \RuntimeException('Cannot create import directory');
}
$lock = fopen($base.'/.lock', 'c');
if (!$lock || !flock($lock, LOCK_EX | LOCK_NB)) {
throw new \RuntimeException('Another import is running');
}
try {
$bytes = file_get_contents($input->getArgument('csv'), false, null, 0, 2_000_001);
if ($bytes === false || strlen($bytes) > 2_000_000) {
throw new \RuntimeException('Unreadable or oversized CSV');
}
$stream = fopen('php://temp', 'w+');
fwrite($stream, $bytes);
rewind($stream);
if (fgetcsv($stream, 0, ',', '"', '') !== ['email', 'consent_reference']) {
throw new \RuntimeException('Unexpected CSV header');
}
$rows = [];
while (($row = fgetcsv($stream, 0, ',', '"', '')) !== false) {
if (count($row) !== 2 || count($rows) >= 1000) {
throw new \RuntimeException('Invalid row or contact limit exceeded');
}
$rows[] = $row;
}
fclose($stream);
// Bump v1 when decision logic changes.
$id = hash('sha256', 'v1'.$bytes.$this->verifier->fingerprint());
$target = $base.'/'.$id;
if (is_dir($target)) {
$output->writeln('Already published: '.$id);
return Command::SUCCESS;
}
$stage = $target.'.tmp.'.bin2hex(random_bytes(6));
if (!mkdir($stage, 0700)) {
throw new \RuntimeException('Cannot create staging directory');
}
$counts = ['accept' => 0, 'review' => 0, 'reject' => 0];
foreach (['clean', 'review', 'reject'] as $name) {
if (file_put_contents($stage.'/'.$name.'.jsonl', '') === false) {
throw new \RuntimeException('Cannot initialize output');
}
}
$seen = [];
foreach ($rows as [$email, $consent]) {
$email = trim($email);
if (isset($seen[$email])) {
continue;
}
$seen[$email] = true;
$result = trim($consent) === ''
? ['decision' => 'review', 'reason' => 'missing_consent_reference',
'evidence' => []]
: $this->verifier->check($email);
$record = ['email' => $email, 'consent_reference' => $consent] + $result;
$name = $result['decision'] === 'accept' ? 'clean' : $result['decision'];
$line = json_encode($record, JSON_THROW_ON_ERROR)."\n";
if (file_put_contents($stage.'/'.$name.'.jsonl', $line, FILE_APPEND)
!== strlen($line)) {
throw new \RuntimeException('Incomplete output write');
}
++$counts[$result['decision']];
}
if (!rename($stage, $target)) {
throw new \RuntimeException('Cannot publish import');
}
$output->writeln(json_encode(['import' => $id] + $counts, JSON_THROW_ON_ERROR));
return Command::SUCCESS;
} finally {
flock($lock, LOCK_UN);
fclose($lock);
}
}
}
Reviewers inspect review.jsonl, check the original consent record, and record an explicit approval, rejection, or correction in the subscriber system. Corrections go through verification again. Only clean.jsonl feeds automatic enrollment, which should independently enforce consent and suppression rules.
Test decisions without external requests
These fixture values are synthetic, not service enums or a claim about its score scale. The tests establish acceptance, conservative fallback, and authentication failure without retrying.
<?php
// tests/EmailVerifierTest.php
namespace App\Tests;
use App\EmailVerifier;
use PHPUnit\Framework\TestCase;
use Psr\Log\NullLogger;
use Symfony\Component\HttpClient\MockHttpClient;
use Symfony\Component\HttpClient\Response\MockResponse;
final class EmailVerifierTest extends TestCase
{
public function testDecisions(): void
{
$path = tempnam(sys_get_temp_dir(), 'email-policy-');
$rule = ['status' => 'fixture-ok', 'recommendation' => 'fixture-allow',
'checks' => ['fixture' => true], 'min' => 7, 'max' => 9];
file_put_contents($path, json_encode(['accept' => [$rule], 'reject' => []]));
try {
$body = ['status' => 'fixture-ok', 'recommendation' => 'fixture-allow',
'score' => 8, 'checks' => ['fixture' => true], 'quota' => ['fixture' => 4]];
foreach ([
[$body, 200, 'accept'],
[array_replace($body, ['status' => 'unknown']), 200, 'review'],
[array_diff_key($body, ['quota' => true]), 200, 'review'],
[$body, 401, 'review'],
] as [$payload, $status, $expected]) {
$calls = 0;
$http = new MockHttpClient(function () use (&$calls, $payload, $status) {
++$calls;
return new MockResponse(json_encode($payload), ['http_code' => $status]);
});
$verifier = new EmailVerifier($http, new NullLogger(), 'TEST_TOKEN', $path);
self::assertSame($expected, $verifier->check('[email protected]')['decision']);
self::assertSame(1, $calls);
}
} finally {
unlink($path);
}
}
}
Deploy, observe, and verify
Run the worker account with a restrictive umask, writable private storage, and production debugging disabled. Keep staging and final directories on the same local filesystem; this locking arrangement assumes one application host. Schedule imports serially.
vendor/bin/phpunit tests
umask 077
APP_ENV=prod APP_DEBUG=0 php bin/console cache:clear
APP_ENV=prod APP_DEBUG=0 php bin/console app:import-contacts contacts.csv
Logs expose HTTP status and attempt counts; command output reports aggregate decisions. Alert on rising review counts and authentication failures. Because authentication uses a query parameter, disable production profiling and redact outbound URLs in HTTP diagnostics, proxies, and tracing systems.
An interrupted import leaves an unpublished staging directory. Remove stale staging directories during maintenance; restarting can repeat billable checks. Completed imports are reused by input and policy fingerprint. Protect artifacts as personal data and apply a retention schedule.
Common surprises are explainable: an empty policy sends remote results to review; changed check structure stops matching; a rotated token requires restarting processes that hold old configuration. A successful HTTP response alone never guarantees acceptance.
- Run tests and verify malformed CSV fails before remote calls.
- Confirm syntax failures reach rejection and unknown evidence reaches review.
- Exercise a mocked 429 and verify subsequent contacts trigger no requests.
- Approve documented policy rules before expecting cleaned contacts.
- Confirm rerunning a published import makes no additional checks.
- Verify permissions, consent enforcement, suppression lists, and manual review ownership.
The useful outcome is a list whose decisions can be explained. Clean contacts move forward, clear failures stop, and uncertainty arrives somewhere a person can resolve it.