How to Set Up Postal v3 on AWS for Production: The Ultimate Enterprise Guide

Postal v3’s official prerequisites specify a dedicated server with at least 2 CPU cores, 4 GiB RAM, and 25 GiB disk, running Docker and MariaDB 10.6+. AWS documents the same EC2 port-25 restriction that affects every self-hosted mail platform. As of July 2026, Postal v3 runs as containerized web, SMTP, and worker services via the postalserver/install helper — not as a single monolithic daemon.

This guide is for DevOps engineers, platform teams, and deliverability specialists deploying Postal v3 on AWS. For managed paths, see Amazon SES consulting and SES migration. Comparing bare MTA options? Read our KumoMTA on AWS guide.

Artifacts: README, postal.yml example, Route53 DNS template, CloudWatch agent config, readiness checklist.

Benchmark pattern (not a cited client) — B2B SaaS notification platform, 50k-200k emails/day, t3.xlarge EC2 + RDS db.t4g.medium MariaDB, HTTP API primary send path. Development AWS footprint: $250-$700/month (compute + RDS + observability in this guide’s cost table).

What broke — A team used the dev docker run mariadb example from Postal docs with the default password and innodb_log_file_size left at RDS defaults. Messages above 8 MB failed silently in the worker queue until log inspection revealed InnoDB row-size errors. Fix: RDS parameter group with 160 MB innodb_log_file_size for a 15 MB max message policy.

Reproduce this — Copy templates from examples/postal-aws-production/. Run postal bootstrap on a non-production hostname before publishing customer DNS.

Executive Summary

Postal v3 on AWS is a containerized mail delivery platform — web UI, HTTP API, SMTP server, and background workers — backed by MariaDB. It fits teams that want self-hosted email with a management interface, not teams that only need a high-throughput MTA engine.

What Is Postal v3?

Postal is an open-source mail delivery platform — not just an SMTP relay. Postal v3 packages:

Virtual mail servers

Each mail server in Postal is a logical sending entity with its own domains, credentials, IP pools, and statistics. This maps well to SaaS products that send on behalf of multiple customers — but reputation isolation still requires disciplined IP and domain strategy.

Functional model

flowchart LR
  app[SendingApp] --> api[PostalHTTPAPI]
  app --> smtp587[SMTPSubmission]
  api --> worker[PostalWorker]
  smtp587 --> worker
  worker --> smtp25[OutboundSMTP]
  smtp25 --> mx[RecipientMX]
  worker --> db[(MariaDBRDS)]
  worker --> webhooks[WebhooksAndEvents]

Why Choose Postal v3?

Feature comparison

Recommendation matrix

AWS Production Architecture

CloudFront, WAF, and ALB do not terminate Postal SMTP traffic. Postal v3 containers use network_mode: host for web and SMTP processes (docker-compose.v3.yml). HTTPS is handled by Caddy in the default install path.

flowchart TD
  internet[Internet] --> r53[Route53]
  app[SendingApplications] --> api[PostalHTTPSAPI]
  app --> smtp587[PostalSMTP587]
  api --> ec2[EC2UbuntuDockerHost]
  smtp587 --> ec2
  ec2 --> eip[ElasticIP]
  eip --> mx[RecipientMX]
  ec2 --> caddy[CaddyHostNetworkTLS]
  ec2 --> rds[RDSMariaDB106]
  subgraph support [AWSSupportingServices]
    cw[CloudWatch]
    ssm[SystemsManager]
    sm[SecretsManager]
    s3[S3Backups]
    gd[GuardDuty]
  end
  ec2 --> cw
  ec2 --> ssm
  rds --> sm

Why each AWS service exists

Infrastructure Design

flowchart LR
  igw[InternetGateway] --> pub[PublicSubnet]
  pub --> ec2[PostalEC2]
  pub --> eip[EIP]
  priv[PrivateSubnet] --> rds[RDSMariaDB]
  ec2 --> rds

VPC baseline

Reverse DNS

Request PTR for each Elastic IP so postal.example.com forward and reverse DNS align — same requirement as any production MTA.

Server Sizing

Postal minimum: 2 vCPU, 4 GiB RAM, 25 GiB disk. Production baselines below account for Docker overhead, MariaDB client load, and queue spikes.

Operating System

Use Ubuntu 22.04 LTS — the official v3 prerequisite script is install-ubuntu.v3.sh (install repo). Install Docker Engine and Docker Compose plugin per Docker docs before Postal bootstrap.

Step-by-Step Installation on AWS

Context: Ubuntu 22.04 LTS EC2, Elastic IP attached, Route53 hostname ready, RDS MariaDB 10.6+ provisioned in private subnets.

0) Provision RDS MariaDB first

Create an RDS MariaDB 10.6+ instance in private subnets before postal initialize — Postal needs credentials that can create and manage postal and postal-* message databases (prerequisites).

Store the master password in Secrets Manager; reference it when editing postal.yml — never commit credentials to git.

1) System packages

sudo apt update && sudo apt upgrade -y
sudo apt install -y git curl jq

2) Docker (official)

# Context: Docker Engine + Compose plugin — see https://docs.docker.com/engine/install/ubuntu/
curl -fsSL https://get.docker.com | sudo sh
sudo docker version && sudo docker compose version

3) Clone Postal v3 install helper

sudo git clone https://github.com/postalserver/install /opt/postal/install
sudo ln -sf /opt/postal/install/bin/postal /usr/bin/postal

4) Bootstrap configuration

# Context: replace postal.example.com with your Route53 hostname
sudo postal bootstrap postal.example.com

This generates /opt/postal/config/postal.yml, signing.key, and Caddyfile.

5) Configure RDS in postal.yml

Edit /opt/postal/config/postal.yml — use v2 format (version: 2). Point main_db and message_db at RDS. See postal.yml.example.

main_db:
  host: postal-db.xxxx.us-east-1.rds.amazonaws.com
  username: postal_admin
  password: '<from-secrets-manager>'
  database: postal

6) Initialize database and admin user

sudo postal initialize
sudo postal make-user

7) Start Postal

sudo postal start
sudo postal status

8) Start Caddy for TLS

# Context: from Postal installation docs — Caddy uses host network
sudo docker run -d \
  --name postal-caddy \
  --restart always \
  --network host \
  -v /opt/postal/config/Caddyfile:/etc/caddy/Caddyfile \
  -v /opt/postal/caddy-data:/data \
  caddy

9) Verify

• Browse https://postal.example.com and log in
• Create first virtual mail server in UI
• Send test via API (see below)

Configure Postal for Production

DNS block in postal.yml

Per DNS configuration docs:

dns:
  mx_records:
    - mx1.postal.example.com
    - mx2.postal.example.com
  spf_include: spf.postal.example.com
  return_path_domain: rp.postal.example.com
  route_domain: routes.postal.example.com
  track_domain: track.postal.example.com

IP pools

Enable postal.use_ip_pools: true and assign pools per mail server in the UI. Separate transactional and marketing streams onto different pools before scaling volume.

HTTP API send example

Context: API key from Postal mail server credentials page

curl --location 'https://postal.example.com/api/v1/send/message' \
  --header 'X-Server-API-Key: YOUR_SERVER_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "to": ["user@example.com"],
    "from": "notifications@yourdomain.com",
    "subject": "Test",
    "plain_body": "Postal v3 on AWS test"
  }'

RDS parameter: innodb_log_file_size

Postal requires innodb_log_file_size ≥ 10× max message size. For 15 MB messages, set 160 MB or higher in your RDS parameter group before production traffic.

Route53 DNS Configuration

Publish records from route53-records.example.txt:

Run postal default-dkim-record for DKIM TXT on the return-path domain.

Security Best Practices

• SSM Session Manager instead of public SSH
• Secrets Manager for RDS passwords — inject at boot via user-data or SSM Parameter Store
• IAM instance role least privilege: CloudWatch, S3 backup bucket, Secrets read
• Security groups — no 3306 from internet; restrict SMTP submission sources
• signing.key permissions 600, root-owned under /opt/postal/config
• Patch cadence — Ubuntu unattended upgrades + Docker image updates via postal upgrade workflow
• GuardDuty + Inspector on EC2

SSH hardening

# Context: /etc/ssh/sshd_config on Postal EC2
PermitRootLogin no
PasswordAuthentication no
PubkeyAuthentication yes

Monitoring Architecture

flowchart LR
  ec2[PostalEC2] --> cwa[CloudWatchAgent]
  cwa --> cwm[Metrics]
  cwa --> cwl[Logs]
  cwm --> alarms[Alarms]
  alarms --> sns[SNS]
  rds[RDS] --> rdsi[RDSMetrics]
  rdsi --> alarms

Priority alarms

Deploy cloudwatch-agent.json on the EC2 host.

Logging Pipeline

flowchart TD
  docker[DockerContainers] --> syslog[HostSyslog]
  syslog --> cwl[CloudWatchLogs]
  cwl --> s3[S3Archive]
  s3 --> athena[Athena]

• Postal logging.stdout: true in config for container log capture
• Retention: 14-30 days CloudWatch hot, 90-365 days S3 cold

Logrotate on EC2

# Context: /etc/logrotate.d/postal-host — host-level logs alongside Docker
/var/log/syslog {
  daily
  rotate 14
  compress
  delaycompress
  missingok
  notifempty
}

Docker container logs under /var/lib/docker/containers/ grow quickly under high volume — monitor disk and set CloudWatch agent inclusion carefully to control ingest cost.

Email Deliverability

flowchart LR
  dns[DNSAuth] --> warmup[IPWarmup]
  warmup --> send[ConservativeVolume]
  send --> monitor[PostmasterAndComplaints]
  monitor --> tune[PoolAndCadenceTuning]

• Warm up each new Elastic IP gradually
• Keep transactional and marketing on separate IP pools
• Monitor Google Postmaster, Microsoft SNDS, complaint rates in Postal UI
• Enforce SPF, DKIM (Postal-generated), DMARC on customer domains
• List-Unsubscribe headers on bulk streams

High Availability

Backup /opt/postal/config (including signing.key) to S3 versioned bucket daily.

flowchart LR
  fail[NodeFailure] --> dns[UpdateDNSorEIP]
  dns --> standby[StandbyPostalHost]
  standby --> rds[RDSMultiAZ]
  standby --> restore[RestoreConfigFromS3]

Performance Tuning

EC2 and Docker

• EBS gp3 with provisioned IOPS for /var/lib/docker
• Adequate inode headroom on Docker volume
• postal status — ensure worker container healthy under load

sysctl baseline

# Context: /etc/sysctl.d/99-postal.conf
net.core.somaxconn = 4096
net.ipv4.ip_local_port_range = 10240 65535
fs.file-max = 2097152

Cost Optimization

Savings: RDS Reserved Instances, Graviton (t4g/m7g) where tested, S3 lifecycle for logs, right-size EC2 after 30-day baseline.

Troubleshooting

sequenceDiagram
  participant App
  participant Postal as PostalAPI
  participant Worker
  participant MX as RecipientMX
  App->>Postal: POST /api/v1/send/message
  Postal->>Worker: Queue message
  Worker->>MX: SMTP delivery
  MX-->>Worker: 250/4xx/5xx
  Worker-->>App: Webhook event

Maintenance Cadence

Do’s and Don’ts

Do’s (30)

Don’ts (30)

Common Real-World Mistakes (25)

Production Readiness Checklist (100+)

Infrastructure

• Dedicated EC2 provisioned
• Elastic IP attached
• Ubuntu 22.04 LTS hardened
• Docker and Compose installed
• EBS gp3 sized for Docker growth
• VPC flow logs enabled
• NAT not required for public-subnet EC2 SMTP path documented

Database

• RDS MariaDB 10.6+ provisioned
• Multi-AZ enabled (production)
• Parameter group: innodb_log_file_size sized
• Automated backups configured
• SG allows 3306 from EC2 only

Postal platform

• install helper cloned to /opt/postal/install
• postal bootstrap completed
• postal.yml v2 format with RDS hosts
• postal initialize successful
• Admin user created
• postal start — all containers up
• Caddy TLS valid
• First virtual mail server created

DNS

• postal.example.com A record
• PTR aligned
• spf.postal.example.com TXT
• rp.postal.example.com records + DKIM
• routes.postal.example.com MX
• track.postal.example.com (if used)
• Customer domain SPF includes

Security

• Secrets Manager for DB passwords
• SSM Session Manager enabled
• SSH restricted
• signing.key permissions verified
• IAM least privilege

Deliverability

• IP warmup plan documented
• IP pools configured
• DMARC on sending domains
• Postmaster tools access
• Complaint threshold defined

Monitoring

• CloudWatch agent deployed
• CPU/disk/RDS alarms
• Synthetic API send probe
• Log archive to S3

Operations

• Backup of /opt/postal/config to S3
• Upgrade runbook documented
• DR drill scheduled
• On-call escalation defined

Networking (extended)

• Internet Gateway attached to VPC
• Public route table has 0.0.0.0/0 to IGW
• Private route tables for RDS subnets only
• NACLs documented (keep simple; SGs primary)
• Elastic IP association documented in runbook
• SMTP submission sources restricted in SG
• Outbound HTTPS allowed for Docker pulls and apt
• DNS resolver reachable from EC2
• NTP/chrony synchronized
• IPv6 posture documented (Postal docs show AAAA optional)

SMTP and API (extended)

• SMTP port 25 listener verified (postal status)
• SMTP submission on 587 tested if enabled
• HTTP API send test from application subnet
• Webhook endpoints reachable from worker
• Bounce webhook URL registered per mail server
• Message retention policy documented
• Maximum message size aligned with RDS innodb setting
• Rate limits per mail server reviewed
• Suppression lists exported periodically
• Dead-letter / held message review process defined

Compliance and audit (extended)

• CloudTrail enabled for AWS API changes
• Config rules for public SG detection
• GuardDuty enabled
• Inspector scans on EC2
• Log retention meets policy
• Access reviews scheduled quarterly
• Change management ticket for postal.yml edits
• Data classification for message metadata documented
• Encryption at rest on RDS and EBS verified
• Incident response playbook includes email outage

Scaling and HA (extended)

• Capacity model by mail server documented
• RDS storage autoscaling threshold set
• EC2 vertical scale trigger defined (CPU sustained > 70%)
• Second EC2 standby image documented for active-passive
• Config sync mechanism (S3 versioned bucket)
• Failover DNS/EIP runbook tested
• Performance baseline captured before scale-up
• Docker image version pinned in upgrade notes
• Worker restart procedure documented
• Load test on API path completed in staging

Webhooks, Bounces, and Event Handling

Postal exposes delivery events through webhooks configured per mail server. On AWS, terminate webhooks on HTTPS endpoints in your VPC (ALB + ACM is appropriate here — unlike SMTP).

Point webhooks at an internal API Gateway or ALB-backed service with authentication. Log webhook payloads to S3 via Firehose for replay during incident analysis.

Upgrading Postal v3

Postal upgrades require reading official upgrading documentation before each change. Production-safe pattern on AWS:

1. Snapshot RDS and /opt/postal/config to S3.
2. Pull latest install helper: cd /opt/postal/install && sudo git pull.
3. Run postal upgrade (per current install CLI).
4. Verify postal status — all containers healthy.
5. Send synthetic API + SMTP probes before restoring full traffic.

Never upgrade during peak send windows. Treat signing.key immutability as a hard constraint unless you understand DKIM and signing impacts.

CloudWatch Alarm Example

# Context: CloudFormation snippet — EC2 CPU high for Postal host
Resources:
  PostalCpuAlarm:
    Type: AWS::CloudWatch::Alarm
    Properties:
      AlarmName: postal-ec2-cpu-high
      Namespace: AWS/EC2
      MetricName: CPUUtilization
      Dimensions:
        - Name: InstanceId
          Value: i-0123456789abcdef0
      Statistic: Average
      Period: 300
      EvaluationPeriods: 3
      Threshold: 80
      ComparisonOperator: GreaterThanThreshold
      AlarmActions:
        - arn:aws:sns:us-east-1:123456789012:email-ops-alerts

Add companion RDS DatabaseConnections and FreeStorageSpace alarms — worker backlog often correlates with DB pressure before CPU spikes on EC2.

IAM Instance Role (Minimal)

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "secretsmanager:GetSecretValue",
        "cloudwatch:PutMetricData",
        "logs:CreateLogStream",
        "logs:PutLogEvents",
        "s3:PutObject"
      ],
      "Resource": "*"
    }
  ]
}

Tighten Resource ARNs to your Secrets Manager secret, log groups, and backup bucket in production accounts.

Postal v3 vs KumoMTA on AWS — Decision Detail

Both run on EC2 with Elastic IPs and Route53 DNS. The operational split:

Our take: start with Postal when the team needs a visible control plane and HTTP API sends. Graduate to KumoMTA when queue policy complexity and throughput outgrow UI-driven configuration — or move outbound to SES when ops cost exceeds ESP economics.

DNS Flow Diagram

flowchart TD
  cfg[postal.yml dns block] --> r53[Route53]
  r53 --> mainHost[postal.example.com A]
  r53 --> spfInc[spf.postal.example.com TXT]
  r53 --> rpDom[rp.postal.example.com MX TXT DKIM]
  r53 --> routesDom[routes.postal.example.com MX]
  mainHost --> ptr[PTR on Elastic IP]
  ptr --> trust[MailboxProviderTrust]

Disaster Recovery Flow

flowchart LR
  outage[EC2Failure] --> promote[AttachEIPtoStandby]
  promote --> restore[RestoreConfigFromS3]
  restore --> rds[RDSMultiAZFailoverIfNeeded]
  rds --> verify[APIandSMTPProbes]
  verify --> traffic[RestoreSends]

What to Do This Week

1. Provision EC2 + RDS MariaDB + Elastic IP in a non-production AWS account.
2. Run postal bootstrap and point postal.yml at RDS.
3. Publish Postal DNS records (spf, return-path, main host) in Route53.
4. Create first virtual mail server; send API and SMTP test messages.
5. Enable CloudWatch alarms and config backup to S3.
6. Document IP warmup plan before customer traffic.

What This Post Doesn’t Cover

• Hosted Postal offerings (third-party managed Postal platforms).
• Full Kubernetes deployment of Postal (EC2 Docker host is the official path).
• Postal v2 migration specifics — see Postal upgrading docs.
• Legal/compliance counsel per jurisdiction.

For hybrid or migration paths, see Amazon SES consulting and How to Migrate from SendGrid to Amazon SES.

FactualMinds Expert Recommendations

FactualMinds is an AWS Select Tier Consulting Partner with email infrastructure expertise.

Contact us to discuss your email infrastructure →