Documentation

Everything you need to set up, configure, and get the most out of MailPulse.

Introduction

MailPulse is an email deliverability monitoring platform built specifically for AWS SES. It helps you track delivery rates, detect issues before they hurt your sender reputation, and optimize your email performance.

With MailPulse you can:

Monitor delivery rates, bounces, and complaints in real-time
Get smart alerts when metrics exceed thresholds
Generate professional PDF and CSV reports
Verify email addresses before sending
A/B test subject lines with statistical confidence
Find the best send times with engagement heatmaps
Send emails directly through your SES configuration

Quick Start

Get up and running in 5 minutes.

Step 1: Create an Account

Go to app.getmailpulse.net/signup and create your free account.

Step 2: Connect AWS SES

Navigate to Settings → AWS Configuration and enter your credentials:

AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=wJal...
AWS_REGION=us-east-1

Your credentials are encrypted and stored securely. We never have access to other AWS services.

Step 3: Configure Webhooks

MailPulse automatically configures SES webhooks when you connect. This enables real-time monitoring of bounces and complaints.

Step 4: Set Up Alerts

Go to Settings → Alerts and configure your thresholds:

Bounce Rate: Default 5% (recommended: 2-5%)
Complaint Rate: Default 0.1% (AWS threshold)
Sudden Drop: Default 20% vs average

Step 5: Start Monitoring

Your dashboard is now live. Data will start appearing within minutes of your next send.

AWS SES Setup

MailPulse requires an AWS account with SES enabled. Here's how to prepare your environment.

Create IAM User

Create a dedicated IAM user for MailPulse with minimal permissions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ses:SendEmail",
        "ses:SendRawEmail",
        "ses:GetSendQuota",
        "ses:GetSendStatistics",
        "ses:ListIdentities",
        "ses:GetIdentityVerificationAttributes"
      ],
      "Resource": "*"
    }
  ]
}

Verify Your Domain

In the AWS SES Console:

Go to Verified identities
Click Create identity
Select Domain and enter your domain
Add the required DNS records (DKIM, SPF)
Wait for verification (usually 5-10 minutes)

Request Production Access

New AWS SES accounts start in sandbox mode. To send to any address:

Go to Account dashboard
Click Request production access
Fill out the form with your use case
Wait for approval (usually 24-48 hours)

⚠️ Important:

In sandbox mode, you can only send to verified email addresses. Production access is required for real-world sending.

Monitoring

MailPulse tracks your email performance in real-time through SES webhooks.

Metrics Tracked

Delivery Rate: Percentage of emails successfully delivered
Bounce Rate: Hard and soft bounces combined
Complaint Rate: Spam complaints per 1000 emails
Open Rate: If tracking is enabled in SES
Reputation Score: 0-100 score based on all metrics

Reputation Score Calculation

Your reputation score (0-100) is calculated as follows:

90-100: Excellent — your sender reputation is strong
70-89: Good — minor issues to address
50-69: Needs attention — action required
Below 50: Critical — immediate action needed

Data Retention

MailPulse retains your data based on your plan:

Free: 7 days
Starter: 90 days
Pro: 1 year

Alerts

Get notified when something goes wrong with your email delivery.

Alert Types

Bounce Rate Exceeded: When bounce rate crosses your threshold
Complaint Rate Exceeded: When complaint rate crosses your threshold
Sudden Drop: When delivery drops significantly vs average
Blocked Sender: When a sender IP or domain is blocked

Notification Channels

Email: SMTP notifications to any address
Slack: Webhook notifications to your channel
In-App: Real-time alerts in the dashboard

Configuring Slack

To receive Slack notifications:

Create an Incoming Webhook in your Slack workspace
Copy the webhook URL
Paste it in Settings → Notifications → Slack Webhook URL

Reports

Generate professional deliverability reports for your team or clients.

Report Types

Overall Summary: All domains combined
Per-Domain: Detailed breakdown by sending domain
Trends: 7d, 30d, 90d trend analysis

Export Formats

PDF: Beautiful reports with charts and tables
CSV: Raw data for analysis in Excel/Sheets

White-Label Reports (Pro)

Pro users can customize reports with their own branding:

Custom logo
Custom colors
Custom footer text

Email Verification

Validate email addresses before sending to improve deliverability.

What We Check

Format: RFC 5322 compliance
DNS: MX record existence
Disposable: 100+ known disposable email domains
Free Provider: Gmail, Yahoo, Outlook, etc.

Bulk Verification

Pro users can verify up to 1,000 emails at once via API or dashboard.

POST /api/verification/verify-bulk
Content-Type: application/json

{
  "emails": [
    "[email protected]",
    "[email protected]",
    "[email protected]"
  ]
}

API Response

{
  "results": [
    {
      "email": "[email protected]",
      "valid": true,
      "format_ok": true,
      "dns_ok": true,
      "mx_found": true,
      "disposable": false,
      "free_provider": false,
      "confidence": 0.95
    }
  ]
}

A/B Testing

Compare subject lines and find what resonates with your audience.

How It Works

Create a test with two variants (A and B)
Set the sample size for each variant
Start the test — MailPulse splits your audience
Track opens and clicks for each variant
Statistical Z-test calculates confidence level

Statistical Confidence

MailPulse uses a Z-test to determine statistical significance:

90% confidence: Likely a winner
95% confidence: Confident winner
99% confidence: Definitive winner

Engagement Heatmap

Discover the best times and days to send your emails.

How It Works

MailPulse analyzes your historical engagement data to create a visual heatmap showing when your audience is most active.

Sending Recommendations

Based on your heatmap data, MailPulse provides AI-powered recommendations for optimal send times.

SES Direct Sending

Send emails directly from MailPulse using your SES configuration.

Setup

Go to Settings → SES Configuration
Enter your AWS credentials (same as monitoring)
Select your verified sender identity
Start sending

API Usage

POST /api/ses/send
Content-Type: application/json

{
  "from": "[email protected]",
  "to": ["[email protected]"],
  "subject": "Hello from MailPulse",
  "html": "<h1>It works!</h1>",
  "text": "It works!"
}

Quota Management

Check your SES sending quota:

GET /api/ses/quota

{
  "max24Hour": 200,
  "maxSendRate": 1,
  "sentLast24Hours": 42
}

API Overview

MailPulse provides a RESTful API for all features.

Base URL

https://api.getmailpulse.net

Response Format

All responses are JSON with consistent structure:

{
  "success": true,
  "data": { ... },
  "message": "Optional message"
}

Error Format

{
  "success": false,
  "error": "Error description",
  "code": "ERROR_CODE"
}

Authentication

All API requests require a JWT token in the Authorization header.

Login

POST /api/auth/login
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "your-password"
}

Response:
{
  "access_token": "eyJ...",
  "token_type": "bearer"
}

Using the Token

Authorization: Bearer eyJ...

API Endpoints

Authentication

POST /api/auth/login — Login and get token
POST /api/auth/register — Create account

Emails

GET /api/emails — List all emails
GET /api/emails/:id — Get email details

Alerts

GET /api/alerts — List alerts
GET /api/alerts/config — Get alert config
PUT /api/alerts/config — Update alert config
PUT /api/alerts/:id/read — Mark as read
PUT /api/alerts/:id/resolve — Resolve alert

Reports

GET /api/reports — Overall report
GET /api/reports/domain/:domain — Domain report
GET /api/reports/trends — Trend analysis
GET /api/reports/export/csv — Export CSV
GET /api/reports/export/pdf — Export PDF

Verification

POST /api/verification/verify — Verify single email
POST /api/verification/verify-bulk — Verify multiple
POST /api/verification/disposable/check — Check disposable

A/B Testing

GET /api/ab-tests — List tests
POST /api/ab-tests — Create test
POST /api/ab-tests/:id/start — Start test
POST /api/ab-tests/:id/complete — Complete test

Heatmap

GET /api/heatmap — Get heatmap data
GET /api/heatmap/recommendations — Best send times

SES

POST /api/ses/configure — Configure SES
POST /api/ses/send — Send email
GET /api/ses/quota — Get quota

Troubleshooting

Webhook Not Receiving Data

Verify your AWS credentials are correct
Check that SNS topic is subscribed and confirmed
Ensure the webhook endpoint is accessible from the internet
Check the webhook logs in Settings → Webhooks

Low Reputation Score

Review your email list — remove invalid addresses
Check for purchased or rented lists (don't use them)
Implement double opt-in for new subscribers
Monitor complaint rate and remove complainers
Check blacklists at mxtoolbox.com

Alerts Not Triggering

Verify alert thresholds are configured correctly
Check notification channel is set up (email/Slack)
Ensure the evaluation cron is running
Check the alerts table for existing alerts

FAQ

Is MailPulse secure?

Yes. AWS credentials are encrypted at rest. All API calls use HTTPS. We follow security best practices including CSP headers, XSS protection, and rate limiting.

Can I use MailPulse with multiple AWS accounts?

Yes. MailPulse supports multi-tenant architecture. You can configure different AWS credentials per tenant.

Do you support SES v2?

Currently, MailPulse uses SES v1 API. SES v2 support is on our roadmap.

What's the difference between free and paid plans?

Free plan includes 100 emails/month and 1 domain. Paid plans increase limits and add features like A/B testing, heatmap, API access, and white-label reports.

How do I cancel my subscription?

Go to Settings → Billing and click Cancel Subscription. Your account will downgrade to Free at the end of the billing period.

Ready to get started?

Create your free account and start monitoring in 5 minutes.

Start Free →