Send Drupal Email with the AhaSend Module

​

Prerequisites

• Drupal 10.6 or later, or Drupal 11, with PHP 8.1 or later, Composer and Drush.
• A verified sending domain.
• An API v2 key.

​

Install the Module

composer require drupal/ahasend:^2.0
drush en ahasend -y

drush en mailer_override -y

​

Add the AhaSend Transport

1. At Configuration → System → Basic site settings, set the site’s Email address to an address on your verified domain. Drupal sends from this address by default.
2. Open /admin/config/system/mailer/transport, choose AhaSend (API v2) as the Transport type and click Add transport.
3. Enter a label and fill in the AhaSend fields:

   Field	Value
   API key	Your aha-sk- key. The saved key is never shown again; select Change API key to replace it.
   Account ID	Your account ID (a UUID).
   Mode	Live, or a simulated result: Sandbox: deliver, Sandbox: bounce, Sandbox: defer, Sandbox: fail or Sandbox: suppress.
   Open tracking, Click tracking	Account default, On or Off. See open tracking and click tracking.

4. Set Mode to Sandbox: deliver for your first tests. AhaSend records sandbox sends and sends their webhook events, but delivers nothing. See sandbox mode.
5. Click Test connection. It calls the ping endpoint, which checks only the API key. It does not check the account ID, the key’s scope or your sender address; the first real send does.
6. Save the transport, then click Set as default next to it in the transport list.

​

Send a Test Email

• Symfony Mailer 1.x: open the Test tab at /admin/config/system/mailer/test.
• Mailer Plus 2.x: open /admin/config/system/mailer.

​

Receive Delivery Events with Webhooks

1. Open Configuration → Web services → AhaSend (/admin/config/services/ahasend) and copy the Webhook URL, for example https://example.com/ahasend/webhook.
2. In the AhaSend dashboard, open Webhooks, click Add Webhook, paste the URL, choose the events to send and create the webhook. See webhooks.
3. Copy the Webhook Secret from the webhook’s details page, paste it into Signing secret in Drupal and save.
4. Send a sandbox test email. After a short delay, its entry in the message log shows the reception and delivery events.

​

Message Log

• Messages: one entry per recipient, with the send time, subject, sender, recipient and status. The status follows the webhook events received for the message and uses the dashboard’s names: Received, Deferred, Delivered, Opened, Clicked, Bounced, Failed or Suppressed. Until the first event arrives, or if no webhook is set up, it shows the result AhaSend returned when the email was sent, such as Queued. Open an entry to see its delivery timeline from webhooks, such as Message Delivered, Message Deferred, Message Bounced or Message Opened, with the receiving server’s SMTP response when AhaSend reports one.
• Events: account-level events that belong to no single message, such as suppressions and DNS errors.

​

Keep Secrets Out of Configuration

1. Install and enable it:
   composer require drupal/key
   drush en key -y
   
2. At /admin/config/system/keys, add a key of type Authentication that uses the File or Environment provider. A key that uses the Configuration provider is exported too, and the module warns you when you select one.
3. In the transport form, set API key source to Use a key from the Key module and select the key. In the AhaSend settings form, do the same with Signing secret source.

// Symfony Mailer 1.x.
$config['symfony_mailer.mailer_transport.TRANSPORT_ID']['configuration']['api_key'] = getenv('AHASEND_API_KEY');
// Mailer Plus 2.x.
$config['mailer_transport.mailer_transport.TRANSPORT_ID']['configuration']['api_key'] = getenv('AHASEND_API_KEY');
// Webhook signing secret.
$config['ahasend.settings']['webhook_secret'] = getenv('AHASEND_WEBHOOK_SECRET');

​

React to Webhook Events in Code

<?php

namespace Drupal\mymodule\EventSubscriber;

use Drupal\ahasend\Event\AhaSendWebhookEvent;
use Drupal\Core\Logger\LoggerChannelFactoryInterface;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

final class AhaSendBounceSubscriber implements EventSubscriberInterface {

  public function __construct(
    private readonly LoggerChannelFactoryInterface $loggerFactory,
  ) {}

  public static function getSubscribedEvents(): array {
    return [AhaSendWebhookEvent::RECEIVED => ['onWebhook', 0]];
  }

  public function onWebhook(AhaSendWebhookEvent $event): void {
    if ($event->getType() !== 'message.bounced') {
      return;
    }
    $recipient = $event->getData()['recipient'] ?? '';
    $this->loggerFactory->get('mymodule')->warning('AhaSend reported a bounce for @recipient.', [
      '@recipient' => $recipient,
    ]);
  }

}

services:
  mymodule.ahasend_bounce_subscriber:
    class: Drupal\mymodule\EventSubscriber\AhaSendBounceSubscriber
    arguments: ['@logger.factory']
    tags:
      - { name: event_subscriber }

​

Troubleshooting

• AhaSend (API v2) is missing from the transport types: clear caches with drush cr.
• Test connection passes, but emails fail: check the account ID, that the key’s scope covers your sender domain, and that the sender address uses a verified domain. AhaSend’s error message is in Reports → Recent log messages; see API errors.
• Emails are accepted but never arrive: check that Mode is Live and that the API key is not a sandbox key.
• Core emails skip AhaSend on Mailer Plus 2.x: enable Mailer Override and the override for those emails.
• The webhook URL answers 404: no signing secret is saved, or the selected key is missing or empty.
• Webhook deliveries get 401: the signing secret does not match the webhook, or the server clock is more than 5 minutes off.
• Webhooks stopped arriving: AhaSend disables a webhook after more than 100 consecutive failed deliveries. Fix the cause, then enable it again in the dashboard.

​

Related Guides

• Domain setup, API credentials, scoped credentials and sandbox mode.
• Webhooks, bounces and suppressions, open tracking and click tracking.
• Troubleshooting, API errors and key security.
• The module’s project page and issue queue.