MailerSend Configuration

MailerSend is used for transactional email delivery via SMTP and webhook-based bounce handling.

SMTP Configuration

Email delivery is handled through MailerSend’s SMTP relay service.

SMTP Settings

SMTP Host: smtp.mailersend.net
SMTP Port: 587
Encryption: TLS (STARTTLS)
Authentication: Plain

Setting Up SMTP Credentials

Log in to your MailerSend account
Navigate to Domains page
Click Manage next to your verified domain
Scroll down to the SMTP section
Click Generate new user to create SMTP credentials
Copy the generated Username and Password

Adding SMTP Credentials to Rails

Add the SMTP credentials to your production Rails credentials:

EDITOR="vim" bin/rails credentials:edit --environment=production

Add the following structure:

mailersend:
  smtp_host: smtp.mailersend.net
  smtp_port: "587"
  smtp_domain: immersive-app.com
  smtp_username: your_smtp_username
  smtp_password: your_smtp_password
  from_email: noreply@immersive-app.com

Webhook Configuration

MailerSend webhooks are used to receive notifications about email events such as bounces, spam complaints, and unsubscribes.

Webhook Authentication

MailerSend webhooks use a signing secret (not an API key) to verify the authenticity of webhook requests. Each webhook request includes a Signature header that must be verified.

Setting Up Webhooks

Create a Webhook in MailerSend:
- Navigate to Domains page in MailerSend
- Click Manage next to your domain
- Scroll down to the Webhooks section
- Click Add webhook
- Enter the endpoint URL: https://immersive-app.com/webhooks/mailersend
- Provide a descriptive webhook name
- Select the events to monitor:
  - activity.soft_bounced
  - activity.hard_bounced
  - activity.spam_complaint
  - activity.unsubscribed
- Click Save webhook
Retrieve the Signing Secret:
- After creating the webhook, locate it in the Webhooks section
- Click on the webhook to view its details
- Copy the Signing Secret value

Add Signing Secret to Rails Credentials:

EDITOR="vim" bin/rails credentials:edit --environment=production

Add the signing secret to your mailersend credentials:

mailersend:
  smtp_host: smtp.mailersend.net
  smtp_port: "587"
  smtp_domain: immersive-app.com
  smtp_username: your_smtp_username
  smtp_password: your_smtp_password
  from_email: noreply@immersive-app.com
  webhook_signing_secret: your_webhook_signing_secret

Webhook Signature Verification

The webhook controller automatically verifies webhook signatures using HMAC SHA256:

Extracts the Signature header from the request
Computes HMAC SHA256 hash of the request body using the signing secret
Compares the computed hash with the signature header using secure comparison
Rejects the request if signatures don’t match

Webhook Endpoint

URL: /webhooks/mailersend
Method: POST
Content-Type: application/json

Supported Webhook Events

The application handles the following MailerSend webhook events:

activity.hard_bounced: Permanent email delivery failure
activity.soft_bounced: Temporary email delivery failure
activity.spam_complaint: Recipient marked email as spam
activity.unsubscribed: Recipient unsubscribed from emails

Webhook Payload Structure

MailerSend webhooks send JSON payloads with the following structure:

{
  "type": "activity.hard_bounced",
  "data": {
    "email": {
      "to": "user@example.com"
    },
    "reason": "Mailbox does not exist"
  }
}

Testing Webhooks

MailerSend provides test email addresses for testing bounce scenarios:

Hard Bounce: hard-bounce@bounce-test.mailersend.net
Soft Bounce: soft-bounce@bounce-test.mailersend.net

Send emails to these addresses and monitor your webhook endpoint to verify bounce events are received and processed correctly.

Configuration Summary

All MailerSend configuration is stored in Rails encrypted credentials under the mailersend key:

mailersend:
  smtp_host: smtp.mailersend.net
  smtp_port: "587"
  smtp_domain: immersive-app.com
  smtp_username: your_smtp_username
  smtp_password: your_smtp_password
  from_email: noreply@immersive-app.com
  webhook_signing_secret: your_webhook_signing_secret