Set a Route Slug and Tags for each site in the Sites table. Both support environment variables.

The site comes from the message (e.g. a user's affiliated site) or the current request.

• Route Slug — the site's route replaces the adapter's route.
• Tags — the site's tags are merged with the adapter's tags. Tags with the same name are replaced.

Example: adapter environment=production, site=default + site site=shop → environment=production, site=shop

Every email is sent with Craft context as Lettermint metadata. You can see it with each message in Lettermint.

Empty keys are skipped. For example, craft_email is missing for emails that aren't system messages.

Add your own metadata — metadata set on the message wins over the Craft metadata:

use Symfony\Component\Mailer\Header\MetadataHeader;

$message->getSymfonyEmail()->getHeaders()->add(new MetadataHeader('order_id', '1234'));

Go to Utilities → Lettermint for an overview of your team and project.

✔️ Project checks make sure that:

• the project is live,
• the System Email Address domain — also of each site that overrides it — belongs to the project and is verified,
• all route slugs (adapter and sites) are outgoing routes of the project.

💡 Good to know

• Only the configured project is loaded, never other projects of the team.
• The Project API Token status works without a Team API Token.
• Sections the token can't read are hidden and show a notice.
• The page never waits for Lettermint: it loads its data in the background. Data is fresh for 5 minutes and shared with the dashboard widget. Older data is shown right away while it's reloaded, and before anything is loaded, the page shows its layout as a placeholder. Data is only cached when Lettermint could be reached, so an outage doesn't stick around.
• Click Refresh to reload the data. Saving other settings reloads it as well.
• Access requires the Utilities → Lettermint permission.

Add the Lettermint widget to your dashboard. It's a compact version of the utility and shows:

• team and plan,
• usage this billing period,
• sent, delivered, hard bounces and spam complaints over 28 days, with a daily chart.

It shares its data with the utility. Only users with the Utilities → Lettermint permission can add or see it.

Receive Lettermint webhook events (deliveries, bounces, complaints, …) as Craft events.

Setup

1. In the Lettermint dashboard, create a webhook and choose its events. Use the endpoint URL shown below the Webhook Secret setting, e.g. https://example.com/actions/lettermint/webhook.
2. Copy its signing secret (whsec_…) into Webhook Secret.

Usage

use SomehowDigital\Craft\Lettermint\services\WebhooksService;
use SomehowDigital\Craft\Lettermint\events\WebhookEvent;
use yii\base\Event;

Event::on(WebhooksService::class, WebhooksService::EVENT_RECEIVE_WEBHOOK, function (WebhookEvent $event) {
    if ($event->type === WebhooksService::TYPE_MESSAGE_HARD_BOUNCED) {
        $event->payload->id;   // delivery ID
        $event->payload->data; // event data, e.g. `recipient`
    }
});

Every event type has a TYPE_* constant, e.g. TYPE_MESSAGE_DELIVERED or TYPE_SUPPRESSION_ADDED. Test deliveries from the dashboard use TYPE_WEBHOOK_TEST. New types from Lettermint fire the event too.

[!TIP]

• The same delivery can arrive more than once. Use $event->payload->id to skip duplicates — it stays the same across retries.
• Keep handlers fast. Push slow work to the queue.
• $event->payload is a SomehowDigital\Craft\Lettermint\models\WebhookPayload with the id, event, timestamp and data of the delivery.

Responses and retries

Webhooks are also received while the system is offline.

Check if emails can be sent, e.g. from an uptime monitor.

Setup

1. Generate a token with at least 16 characters and no spaces, e.g. openssl rand -hex 32.
2. Store it in an environment variable, e.g. LETTERMINT_HEALTH_TOKEN.
3. Set Health Token to $LETTERMINT_HEALTH_TOKEN.

[!WARNING] Don't enter the token directly. It would be saved in the project config and end up in version control.

Usage

curl -H "Authorization: Bearer $LETTERMINT_HEALTH_TOKEN" https://example.com/actions/lettermint/health

The overall status is the worst check result: ok, warning or error.

The endpoint is off without a Health Token or in the Standard edition. Results are cached for 60 seconds to stay within Lettermint's rate limits. The endpoint also works while the system is offline.

{
    "status": "warning",
    "date": "2026-11-05T10:00:00+00:00",
    "checks": [
        { "id": "token", "status": "ok", "text": "Lettermint accepts the project API token." },
        { "id": "teamToken", "status": "ok", "text": "Lettermint accepts the team API token." },
        { "id": "usage", "status": "warning", "text": "The monthly volume of the plan is nearly used up, with 46000 of 50000 emails." },
        { "id": "delivery", "status": "ok", "text": "The project is live." },
        { "id": "sender", "status": "ok", "text": "The domain “example.com” of the system email address belongs to the project." },
        { "id": "route", "status": "ok", "text": "Emails use the default route “outgoing” of the project." }
    ],
    "usage": { "used": 46000, "included": 50000, "share": 0.92 }
}

Run the same checks as the health endpoint from the command line. No Health Token needed, and results are never cached.

php craft lettermint/health

ok      token      Lettermint accepts the project API token.
ok      teamToken  Lettermint accepts the team API token.
warning usage      The monthly volume of the plan is nearly used up, with 46000 of 50000 emails.

Status: warning