Forem: Jayen Ashar

Building a Secure Email Migration Tool: OAuth, Encryption, and Privacy by Design

Jayen Ashar — Mon, 09 Feb 2026 11:08:53 +0000

When building tools that handle user credentials and email data, security isn't optional—it's fundamental. Recently, I built a POP3 to Gmail migration service, and I want to share the security architecture decisions that make it trustworthy.

The Security Challenges

Email migration tools face unique security challenges:

Dual credential management: Need both POP3 passwords and Gmail access
Sensitive data: Email content is highly personal/confidential
Continuous access: Background services need long-term credential storage
User trust: Users must trust you with their email history

Architecture Decisions

1. OAuth for Gmail Access

Decision: Use Google OAuth instead of asking for Gmail credentials.

Benefits:

Service never sees user's Google password
Users authenticate directly with Google
Minimal permission scope (gmail.insert only)
Automatic token refresh
Users can revoke access anytime via Google Account settings

Implementation:

// Request minimal scope
const SCOPES = ['https://www.googleapis.com/auth/gmail.insert'];

// Users authenticate with Google, receive OAuth code
// Exchange code for tokens server-side
// Store refresh token encrypted
// Use for automated background sync

Key Insight: The gmail.insert scope allows adding messages but cannot read, modify, or delete existing email. This is the principle of least privilege in action.

2. Client-Side Credential Encryption

Challenge: Need to store POP3 passwords for background sync, but don't want plaintext passwords hitting the server.

Solution: Encrypt passwords in the browser before transmission.

Architecture:

Generate public/private key pair (one-time, server-side)
Publish public key at /pop3-migrator.pub.asc
Client fetches public key
Client encrypts POP3 password in browser
Encrypted password sent to server
Server decrypts only when needed for POP3 connection

Why This Matters:

Network sniffing won't reveal passwords (already encrypted)
Database breach won't reveal plaintext passwords
Minimizes exposure window

3. Privacy by Design: Delete After Sync

Challenge: Storing email metadata creates privacy risks and compliance burdens.

Solution: Delete messages from POP3 server after successful sync to Gmail.

Benefits:

No need to store what emails users have
No message metadata in our database
Reduces GDPR/privacy compliance surface area
Users' email lives only in Gmail (single source of truth)

Trade-off:

Cannot re-sync the same messages
Users must accept deletion

Implementation Note: This isn't just a privacy feature—it also prevents duplicates if other migration tools are used in parallel.

4. Failure Transparency: Email Notifications

Challenge: Silent failures are terrible UX and leave users wondering if migration worked.

Solution: Send email notifications when messages fail to import.

Example Scenarios:

Oversized messages (>10MB)
Malformed messages
Network failures
API quota exceeded

Why This Matters:
Gmail's now-removed POP3 fetcher failed silently. Users didn't know what didn't sync. Email notifications give users visibility and control.

5. Minimal Data Collection

Principle: Only store what's necessary for the service to function.

What We Store:

OAuth refresh tokens (encrypted)
POP3 credentials (encrypted)
Sync state (which messages already synced)
Configuration (server, port, username)

What We DON'T Store:

Email content
Email metadata (subjects, senders, dates)
User's email list
Read/unread status

Implementation: Use message UIDs (unique identifiers from POP3 server) to track what's synced, but don't store the actual message data.

6. Network Security: SSRF Prevention

Challenge: Users provide hostnames. Malicious actors could target internal services.

Solution: Validate and block private IP ranges.

What We Block:

Localhost (127.0.0.1, ::1)
Private networks (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16)
Link-local addresses
DNS rebinding attempts

Why It Matters: Prevents attackers from using your service to probe internal networks or attack localhost services.

Architecture Trade-offs

Security Through Obscurity?

Some might argue against publishing technical details. However:

Pro: Obscurity adds a small security layer
Con: Open architecture builds user trust
Decision: Share high-level security model, omit specific implementation details (algorithm versions, library names, database schemas)

Stateless vs Stateful?

Stateless: Better security, but can't resume after interruptions
Stateful: Necessary for continuous sync, but requires secure state storage
Decision: Stateful with encrypted state storage

Client-side vs Server-side Encryption?

Client-side: Password never transmitted in plaintext
Server-side: Simpler, but password exposed during transmission
Decision: Client-side encryption for POP3 credentials

Lessons Learned

OAuth is worth the complexity: User trust is higher when they authenticate directly with Google
Encrypt early, decrypt late: Minimize the window where sensitive data is accessible
Privacy by deletion: Not storing data is better than securing stored data
Fail loudly in development, notify users in production: Silent failures are UX disasters
Minimal scope creep: Only request permissions you actually need

Testing Security

Before launch, verify:

[ ] OAuth flow works end-to-end
[ ] Credentials encrypted before leaving browser (check network tab)
[ ] SSRF prevention blocks private IPs
[ ] Oversized messages handled gracefully
[ ] Email notifications sent on failures
[ ] Users can revoke access via Google Account settings

Conclusion

Building secure migration tools requires thinking about:

Authentication: OAuth over password storage
Encryption: Client-side before transmission
Privacy: Delete data you don't need
Transparency: Notify users of failures
Least privilege: Minimal permission scopes

The result is a tool users can trust with their email history.

If you're building similar tools, I hope these patterns help. What security considerations have you faced in your projects?

How to Migrate Legacy POP3 Email to Gmail: A Complete Guide

Jayen Ashar — Sun, 08 Feb 2026 03:35:54 +0000

If you're managing IT for a small business or consulting on email migrations, you've probably encountered the challenge of moving email from legacy POP3 servers to Gmail. Whether it's a cPanel account, an old hosting provider, or an on-premise server, the process is rarely straightforward.

The Problem with Traditional Migration Tools

Most email migration tools fall into two categories:

One-shot migrations that try to transfer everything at once (and often timeout on large mailboxes)
Gmail's built-in POP3 fetcher which Google removed in January 2026 (https://support.google.com/mail/answer/16604719) — it lacked critical features like failure notifications

The common issues include:

Timeouts on large mailboxes
No visibility into progress
Oversized messages blocking entire migrations
Silent failures (you don't know what didn't sync)
All-or-nothing approaches requiring constant connectivity

A Better Approach: Continuous Batch Processing

The solution is to process emails in small, manageable batches with pauses between sessions. This approach:

Avoids timeouts by keeping connections short-lived
Resumes automatically after any interruption
Provides visibility with real-time progress tracking
Handles failures gracefully with email notifications
Respects rate limits with built-in pausing

How It Works

Step 1: OAuth Authentication

Use Google OAuth to get minimal permissions (gmail.insert scope only). This means the service can add emails to Gmail but cannot read, modify, or delete existing messages.

Step 2: Secure Credential Handling

Encrypt POP3 credentials client-side before transmission. This ensures passwords are never transmitted in plain text.

Step 3: Continuous Sync Loop

The service runs a scheduled process:

Connect to POP3 server
List available messages (tracking what's already synced)
Fetch a batch (10-50 messages)
Upload each to Gmail via API
Delete from POP3 on success
Send email notification on failure
Disconnect and pause
Repeat until done

Step 4: Monitor Progress

Track remaining messages in real-time. Get email notifications for oversized messages or other failures.

Key Design Decisions

Why Delete From POP3?

Deletion after successful sync serves two purposes:

Privacy: We don't need to store metadata about your emails
Compatibility: Prevents duplicates if you use other migration tools

Why Batch Processing?

Small batches with pauses:

Reduce server load
Avoid timeout issues
Respect API rate limits
Work reliably over unreliable networks

Why Email Notifications?

Unlike Gmail's former POP3 fetcher which failed silently, email notifications ensure you know when messages need manual handling (e.g., oversized messages).

Common Use Cases

1. cPanel to Google Workspace Migration

Moving a small business from shared hosting to Google Workspace with years of email history.

2. Legacy Server Decommissioning

Archiving emails from an old server before shutting it down.

3. Multi-Account Consolidation

Consolidating multiple old email accounts into a single Gmail account.

4. Transition Period Sync

Continuously syncing an active POP3 account while gradually transitioning to Gmail.

Technical Considerations

Message Size Limits

The service enforces a 10MB limit per message. Messages exceeding this are:

Left on the POP3 server
You receive an email notification
Can be handled manually

Date Preservation

The original message Date header is preserved, so emails appear in Gmail with their original timestamps, not the sync date.

Multiple Mailboxes

You can configure multiple POP3 accounts per Gmail account, each syncing independently.

Best Practices

Start small: Test with one small mailbox first to verify the flow
Monitor regularly: Check progress in the first 24 hours
Plan for oversized messages: Identify and handle these separately
Keep server running: Don't shut down the POP3 server until sync completes
Verify in Gmail: Spot-check synced emails to ensure dates and content are correct

When NOT to Use This Approach

This approach may not be suitable if:

You need to preserve read/unread status (all messages appear unread in Gmail)
You want to keep messages on the POP3 server (deletion is required)
Your POP3 server doesn't support UIDL (for tracking synced messages)
You're using IMAP (this is POP3-specific)

Try It Yourself

If you're facing a POP3 to Gmail migration challenge, you can try this approach at POP3 to Gmail Sync. It's free to use and handles the complexity of continuous, reliable email migration.

Conclusion

Email migration doesn't have to be painful. By using continuous batch processing, secure OAuth, and proactive notifications, you can reliably move even large mailboxes from legacy POP3 servers to Gmail without babysitting the process.

Have you dealt with email migrations? What challenges have you encountered? Share your experiences in the comments!