Email-to-JSON API

A powerful, production-ready temporary email service built with Go that receives emails via SMTP and provides them through a REST API. Perfect for testing email functionality in your applications without needing real email accounts.

What It Does

Provides temporary email addresses that convert incoming emails to JSON via REST API.

Perfect for:

• Testing email functionality in applications
• Receiving webhooks or notifications via email
• Email automation and processing workflows
• Temporary email needs without signup

Why I Built This

This project was built to develop expertise in:

• SMTP protocol implementation - Deep dive into email protocols and RFC standards
• Concurrent request handling in Go - Mastering goroutines, channels, and concurrent patterns
• Building production-ready REST APIs - Implementing proper error handling, validation, and HTTP best practices
• Database optimization and indexing - Query optimization, proper indexing strategies, and efficient data retrieval
• Webhook architecture and retry mechanisms - Building reliable event-driven systems with exponential backoff
• Rate limiting and spam prevention - Implementing API rate limiting and spam detection algorithms

Features

• No registration required - Create temporary emails instantly
• 7-day expiration - Emails auto-expire for privacy
• JSON API - Easy integration with any application
• Attachment support - Files converted to base64
• HTML & Text parsing - Supports both email formats
• Rate limiting - 100 requests/minute per IP
• SQLite storage - Lightweight, no external dependencies

Quick Start

Prerequisites

• Go 1.21 or higher
• Port 2525 (SMTP) and 8080 (API) available

Installation

# Clone the repository
git clone https://github.com/mayas-spec/email-to-json-api.git
cd email-to-json-api

# Install dependencies
go mod download

# Run the server
go run .

The server will start with:

• SMTP server on localhost:2525
• HTTP API on http://localhost:8080

Quick Test

# 1. Create a temporary email address
curl -X POST http://localhost:8080/api/addresses

# Response: {"id":"abc123","email":"test-abc123@localhost","expires_at":"2026-01-20T10:30:00Z"}

# 2. Send an email (requires swaks - see Testing section)
swaks --to test-abc123@localhost \
      --from test@example.com \
      --server localhost:2525 \
      --header "Subject: Test Email" \
      --body "This is a test message"

# 3. Retrieve emails
curl http://localhost:8080/api/emails/abc123

API Documentation

POST /api/addresses

Creates a new temporary email address valid for 7 days.

Request:

curl -X POST http://localhost:8080/api/addresses

Response:

{
  "id": "abc123",
  "email": "test-abc123@yourdomain.com",
  "expires_at": "2026-01-20T10:30:00Z"
}

GET /api/emails/:addressId

Retrieves emails for a specific address ID.

Request:

curl http://localhost:8080/api/emails/abc123?limit=10

Query Parameters:

• limit (optional): Number of emails to return (default: 50, max: 100)

Response:

[
  {
    "id": 1,
    "address_id": "abc123",
    "from": "sender@example.com",
    "to": "test-abc123@yourdomain.com",
    "subject": "Test Email",
    "text_body": "Hello world",
    "html_body": "<p>Hello world</p>",
    "attachments": [
      {
        "filename": "document.pdf",
        "content_type": "application/pdf",
        "data": "base64-encoded-data...",
        "size": 12345
      }
    ],
    "received_at": "2026-01-13T10:30:00Z"
  }
]

GET /health

Health check endpoint.

Response:

{
  "status": "ok",
  "timestamp": "2026-01-13T10:30:00Z"
}

Error Responses

The API returns appropriate HTTP status codes:

• 400 Bad Request - Invalid email format or parameters
• 404 Not Found - Address ID not found
• 410 Gone - Address has expired
• 429 Too Many Requests - Rate limit exceeded
• 500 Internal Server Error - Database or server error

Example error response:

{
  "error": "Address not found"
}

Environment Variables

Configure the server using environment variables:

Variable	Description	Default
DOMAIN	Your domain name	localhost
SMTP_PORT	SMTP server port	2525
API_PORT	HTTP API port	8080
DB_PATH	SQLite database path	./emails.db

Example:

export DOMAIN=tempmail.yourdomain.com
export SMTP_PORT=25
export API_PORT=8080
go run .

Testing

Automated Testing

Use the included test script to verify all functionality:

chmod +x manual_test.sh
./manual_test.sh

The script will:

1. Create a temporary email address
2. Send a test email via SMTP
3. Retrieve and verify the email via API
4. Test error handling

Manual Testing

1. Send Email with swaks

# Install swaks (SMTP testing tool)
brew install swaks  # macOS
apt-get install swaks  # Ubuntu/Debian

# Send test email
swaks --to test-abc123@localhost \
      --from test@example.com \
      --server localhost:2525 \
      --header "Subject: Test Email" \
      --body "This is a test message"

2. Send Email with telnet

telnet localhost 2525
> HELO test.com
> MAIL FROM:<test@example.com>
> RCPT TO:<test-abc123@localhost>
> DATA
> Subject: Test Email
>
> This is a test message.
> .
> QUIT

Production Deployment

1. DNS Configuration

Configure MX record to point to your server:

tempmail.yourdomain.com. IN MX 10 your-server.com.

2. Port Configuration

# Option A: Run as root on port 25
sudo SMTP_PORT=25 go run .

# Option B: Use port forwarding (recommended)
sudo iptables -t nat -A PREROUTING -p tcp --dport 25 -j REDIRECT --to-port 2525

3. Reverse Proxy (nginx)

server {
    listen 80;
    server_name api.yourdomain.com;

    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

4. SSL/TLS (Let's Encrypt)

sudo certbot --nginx -d api.yourdomain.com

5. Systemd Service

Create /etc/systemd/system/email-to-json.service:

[Unit]
Description=Email-to-JSON API
After=network.target

[Service]
Type=simple
User=emailapi
WorkingDirectory=/opt/email-to-json
ExecStart=/opt/email-to-json/email-to-json
Environment=DOMAIN=tempmail.yourdomain.com
Environment=SMTP_PORT=2525
Environment=API_PORT=8080
Restart=always

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable email-to-json
sudo systemctl start email-to-json
sudo systemctl status email-to-json

Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Email Client  │───▶│   SMTP Server   │───▶│    SQLite DB    │
│                 │    │   (port 2525)   │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                │
                                ▼
┌─────────────────┐    ┌─────────────────┐
│   Web Client    │◀───│   HTTP API      │
│                 │    │   (port 8080)   │
└─────────────────┘    └─────────────────┘

Security Considerations

• No authentication - Addresses are publicly accessible via ID
• 7-day expiration - Automatic cleanup prevents data accumulation
• Rate limiting - Prevents abuse (100 req/min per IP)
• 5MB attachment limit - Prevents large file uploads
• Input validation - Email parsing with malformed header handling

For production use:

• Use HTTPS for API endpoints
• Implement authentication if needed
• Monitor disk usage for database
• Set up log rotation
• Consider IP whitelisting for SMTP

Project Structure

.
├── main.go              # Application entry point
├── smtp_server.go       # SMTP server implementation
├── api_server.go        # REST API handlers
├── database.go          # Database operations
├── manual_test.sh       # Testing script
├── go.mod               # Go dependencies
└── README.md            # Documentation

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Test thoroughly with ./manual_test.sh
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request