Skip to main content

Mercury Message Gateways Setup

Amazon Simple Email Service​

Follow these steps to configure Amazon Simple Email Service (SES) for sending transactional and marketing emails from Mercury. Replace any placeholder values with your own.

Step 1: Create a Dedicated SES Identity Email​

  1. In your organization’s admin console (e.g. Microsoft 365 Admin Center), create a new distribution list to serve as your SES “From” address (e.g. [email protected]).
  2. Add any team members who should access SES notifications.
  3. Enable external senders so SES can deliver messages to this address.

Step 2: Provision a New AWS Account​

  1. Sign in to your AWS Organization master account.
  2. Add a new member account dedicated to SES.
  3. Sign out and use the Forgot password flow to set a password for the new account.
  4. Record the account credentials securely.

Step 3: Verify Your Sending Domain​

  1. In the AWS Console, switch to your SES account and select the appropriate Region (e.g. eu-west-1).
  2. Navigate to Amazon SES → Configuration → Identities and click Create identity.
  3. Under Identity Type choose Domain, enter your sending domain (e.g. yourdomain.com), and follow the prompts.
  4. Add the provided DKIM CNAME records to your DNS zone. SES will confirm verification once DNS propagates.
tip

For improved deliverability it is highly recommended to use a custom MAIL FROM. This should be a subdomain of your email domain. E.g. awsmail.yourdomain.com. Once configured, SES will use [email protected] instead of the default [email protected] — giving you better control and branding over your outgoing emails.

Step 4: Create a Configuration Set​

  1. Go to SES → Configuration sets and click Create configuration set.
  2. Name it (e.g. BrandEmailConfig).
  3. Within the new config set, add a Destination of type Amazon SNS.
  4. Select All event types and Create SNS topic when prompted.
  5. Note the SNS Topic ARN for later.

Step 5: Subscribe Mercury to SNS Notifications​

  1. In SNS → Topics, locate your SES events topic.
  2. Click Create subscription:
    • Protocol: HTTPS
    • Endpoint: https://<YOUR_MERCURY_API>/api/AmazonSnsSubscriber/ProcessNotification
  3. Ensure your API endpoint allows anonymous POSTs to /api/AmazonSnsSubscriber/ProcessNotification.
  4. Leave Raw message delivery unchecked.
  5. Use the default retry policy.

Step 6: Create an IAM User for Mercury​

  1. Navigate to IAM → Users and click Add user.
  2. Select Programmatic access only.
  3. On Permissions, attach AmazonSESFullAccess.
  4. Complete the wizard and download the Access Key ID and Secret Access Key.

Step 7: Configure Mercury​

Brand-Level Settings​

In the Mercury admin, go to Brand Settings and add:

KeyValueNotes
AmazonConfigSetBrandEmailConfigThe name of the SES configuration set.
AmazonTopicArn<YOUR_SNS_TOPIC_ARN>ARN created in Step 4.
AmazonAccessKey<IAM_USER_ACCESS_KEY_ID>From Step 6.
AmazonSecretKey<IAM_USER_SECRET_ACCESS_KEY>From Step 6.

Application-Level Settings​

In Settings → Application Settings, add:

KeyValueNotes
SubscriptionCenterUrlhttps://yourdomain.comURL where users can manage email preferences.

Step 8: Confirm SNS Subscription​

  1. Back in SNS → Subscriptions, select your Mercury endpoint subscription.
  2. Click Request confirmation.
  3. Wait until the status changes to Confirmed — SES events will now be delivered to Mercury.
Developer Note

Mercury listens for SES event notifications at /api/AmazonSnsSubscriber/ProcessNotification and automatically processes bounces, complaints, and deliveries.

SMS Service​

Viber Service​