Email Forwarding

mailiam’s email forwarding system allows you to receive emails sent to any address at your domain and forward them to your existing email. This includes both specific address forwarding and catch-all forwarding for unknown addresses.

Quick Start

1. Set Up Domain Forwarding

Configure forwarding for your domain:

curl -X POST https://api.mailiam.dev/forwarding/setup \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "yourdomain.com",
    "forwardTo": "your@gmail.com"
  }'

2. Add MX Records

Add these MX records to your DNS:

Priority  Host            Points to
10        yourdomain.com  inbound-smtp.us-east-1.amazonaws.com

3. Verify Setup

Test your forwarding:

curl https://api.mailiam.dev/forwarding/yourdomain.com/verify

That’s it! Emails sent to any address at your domain will now forward to your specified email.

Forwarding Types

Catch-All Forwarding

Forward all emails to your domain to a single address:

curl -X POST https://api.mailiam.dev/forwarding/domains \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "company.com",
    "type": "catch-all",
    "forwardTo": "team@company.com"
  }'

Use Cases:

Small businesses wanting to catch all customer emails
Personal domains where you want everything in one inbox
Temporary projects needing simple email setup

Specific Address Forwarding

Forward specific email addresses to different destinations:

curl -X POST https://api.mailiam.dev/forwarding/addresses \
  -H "Content-Type: application/json" \
  -d '{
    "address": "support@company.com",
    "forwardTo": "help-desk@company.com"
  }'

Use Cases:

Department-specific routing (sales@, support@, info@)
Employee email aliases
Legacy address migration

Multiple Destination Forwarding

Forward one address to multiple recipients:

curl -X POST https://api.mailiam.dev/forwarding/addresses \
  -H "Content-Type: application/json" \
  -d '{
    "address": "alerts@company.com",
    "forwardTo": ["admin@company.com", "ops@company.com", "security@company.com"]
  }'

Advanced Configuration

Priority-Based Forwarding

Set forwarding priority (specific addresses override catch-all):

# Catch-all setup
curl -X POST https://api.mailiam.dev/forwarding/domains \
  -d '{
    "domain": "company.com",
    "type": "catch-all",
    "forwardTo": "general@company.com",
    "priority": 1
  }'

# Specific address (higher priority)
curl -X POST https://api.mailiam.dev/forwarding/addresses \
  -d '{
    "address": "ceo@company.com",
    "forwardTo": "boss@company.com",
    "priority": 10
  }'

Conditional Forwarding

Forward based on email content or sender:

curl -X POST https://api.mailiam.dev/forwarding/rules \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "company.com",
    "conditions": {
      "subject_contains": ["urgent", "emergency"],
      "sender_domain": "client.com"
    },
    "forwardTo": "escalation@company.com"
  }'

Time-Based Forwarding

Forward to different addresses based on time:

curl -X POST https://api.mailiam.dev/forwarding/schedules \
  -H "Content-Type: application/json" \
  -d '{
    "address": "support@company.com",
    "schedules": [
      {
        "days": ["monday", "tuesday", "wednesday", "thursday", "friday"],
        "hours": "09:00-17:00",
        "timezone": "America/New_York",
        "forwardTo": "support-team@company.com"
      },
      {
        "days": ["saturday", "sunday"],
        "forwardTo": "on-call@company.com"
      }
    ]
  }'

Email Processing Features

Header Preservation

All original email headers are preserved:

From: Original sender address
To: Original destination address
Reply-To: Automatically set to original sender
Subject: Unchanged (with optional prefix)
Message-ID: Original message threading preserved

Subject Line Modification

Add prefixes to forwarded emails:

curl -X PATCH https://api.mailiam.dev/forwarding/addresses/support@company.com \
  -d '{
    "subjectPrefix": "[SUPPORT] "
  }'

Result: [SUPPORT] Customer needs help with product

Attachment Handling

Small Attachments (< 10MB): Forwarded as-is
Large Attachments (> 10MB): Stored in S3, link provided in email
Suspicious Attachments: Quarantined and notification sent

Spam Filtering

Built-in spam protection:

SPF/DKIM Verification: Checks sender authentication
Content Filtering: Scans for spam patterns
Reputation Filtering: Blocks known spam sources
Rate Limiting: Prevents forwarding abuse

Management API

List Forwarding Rules

curl -H "Authorization: Bearer your-token" \
  https://api.mailiam.dev/forwarding/rules

Update Forwarding Destination

curl -X PATCH https://api.mailiam.dev/forwarding/addresses/info@company.com \
  -d '{
    "forwardTo": "new-address@company.com"
  }'

Disable Forwarding

Temporarily disable without deleting:

curl -X PATCH https://api.mailiam.dev/forwarding/addresses/temp@company.com \
  -d '{
    "enabled": false
  }'

Delete Forwarding Rule

curl -X DELETE https://api.mailiam.dev/forwarding/addresses/old@company.com

DNS Configuration

Required MX Records

Add these records to your DNS provider:

Type  Name              Value                                  Priority
MX    yourdomain.com    inbound-smtp.us-east-1.amazonaws.com  10
MX    yourdomain.com    inbound-smtp.us-west-2.amazonaws.com  20

Optional TXT Records

Improve deliverability with these optional records:

Type  Name              Value
TXT   yourdomain.com    v=spf1 include:mailiam.dev ~all
TXT   _dmarc            v=DMARC1; p=none; rua=mailto:admin@yourdomain.com

Subdomain Forwarding

Forward emails from subdomains:

Type  Name                   Value
MX    mail.yourdomain.com    inbound-smtp.us-east-1.amazonaws.com

Integration Examples

Google Workspace Migration

Gradually migrate from Google Workspace:

# Set up catch-all for unmigrated users
curl -X POST https://api.mailiam.dev/forwarding/domains \
  -d '{
    "domain": "company.com",
    "type": "catch-all",
    "forwardTo": "team@company.gmail.com"
  }'

# Migrate specific users
curl -X POST https://api.mailiam.dev/forwarding/addresses \
  -d '{
    "address": "john@company.com",
    "forwardTo": "john.smith@company.gmail.com"
  }'

Customer Support Routing

Route customer emails by department:

# General support
curl -X POST https://api.mailiam.dev/forwarding/addresses \
  -d '{
    "address": "support@company.com",
    "forwardTo": ["tier1@company.com", "manager@company.com"]
  }'

# Sales inquiries
curl -X POST https://api.mailiam.dev/forwarding/addresses \
  -d '{
    "address": "sales@company.com",
    "forwardTo": "sales-team@company.com"
  }'

# Catch remaining emails
curl -X POST https://api.mailiam.dev/forwarding/domains \
  -d '{
    "domain": "company.com",
    "type": "catch-all",
    "forwardTo": "general@company.com"
  }'

Development Environment

Forward emails by environment:

# Production emails
curl -X POST https://api.mailiam.dev/forwarding/domains \
  -d '{
    "domain": "app.com",
    "forwardTo": "alerts@company.com"
  }'

# Staging emails
curl -X POST https://api.mailiam.dev/forwarding/domains \
  -d '{
    "domain": "staging.app.com",
    "forwardTo": "dev-team@company.com"
  }'

Monitoring and Analytics

Forwarding Statistics

View forwarding metrics:

curl -H "Authorization: Bearer your-token" \
  https://api.mailiam.dev/forwarding/stats?domain=company.com

Response:

{
  "domain": "company.com",
  "period": "last_30_days",
  "emails_forwarded": 1250,
  "emails_blocked": 45,
  "top_senders": [
    {"address": "support@client.com", "count": 120},
    {"address": "noreply@service.com", "count": 89}
  ],
  "forwarding_breakdown": {
    "catch_all": 800,
    "specific_addresses": 450
  }
}

Real-time Monitoring

Set up webhooks for forwarding events:

curl -X POST https://api.mailiam.dev/forwarding/webhooks \
  -d '{
    "url": "https://your-app.com/webhook",
    "events": ["email.forwarded", "email.blocked", "rule.matched"]
  }'

Troubleshooting

Common Issues

Emails not being forwarded?

Check MX records are correctly set
Verify forwarding rules are active
Check spam folder of destination email
Ensure domain verification is complete

Some emails missing?

Check for content-based filtering rules
Review spam protection settings
Verify attachment size limits
Check forwarding quotas

Forwarding delayed?

Email forwarding is typically < 5 seconds
Large attachments may cause delays
Recipient server issues can cause delays
Check AWS SES service status

Getting Help

Monitor your forwarding with our dashboard
Check our API Reference for detailed documentation
Contact support at support@mailiam.dev

Security Best Practices

Access Control

Use API keys for authentication
Rotate keys regularly
Implement IP whitelisting for sensitive domains
Monitor forwarding logs for suspicious activity

Email Validation

Enable SPF/DKIM checking
Use DMARC policies
Block emails from suspicious domains
Implement rate limiting

Data Protection

All emails are encrypted in transit
Temporary email storage is encrypted
Attachments are virus-scanned
Personal data is automatically purged

Next Steps

Learn about Forms for contact form integration
Check out Email Sending for outbound email
Explore our API Reference for complete documentation