FormMaillyGo API Documentation

📧 Overview

FormMaillyGo is a powerful email service built with Go that runs on AWS Lambda. It allows you to send emails individually or in batches through simple REST API endpoints. Think of it as your personal email sending service that you can integrate into any website or application.

🚀 Base URL

Base URL

https://your-lambda-function-url.amazonaws.com

📡 API Endpoints

🏠 Home Page

Purpose: Display the main page of the FormMaillyGo service.

HTTP

GET /

When to use:

To check if the service is running
To display a welcome page for your email service

Response: HTML page with service information

Example:

curl

curl https://your-api-url.com/

📧 Contact Form Email

Purpose: Receive contact form submissions directly to your email.

HTTP

POST /api/contact

When to use:

Contact forms on websites

Request Body

JSON

{
  "name": "John Doe",
  "email": "john@example.com",
  "subject": "Hello from my website",
  "message": "This is a test message from the contact form.",
  "product_name": "My Awesome Website",
  "product_website": "https://mywebsite.com"
}

Contact Form Field Descriptions

name (required): Name of the person sending the email (max 100 characters)
email (required): Valid email address of the contact form field (max 255 characters)
subject (required): Email subject line (max 300 characters)
message (required): Email content/body (no limit)
product_name (optional): Name of your product/website (defaults to "FormMaillyGo")
product_website (optional): Your website URL (defaults to FormMaillyGo URL)

Success Response (201)

JSON

{
  "message": "Email sent successfully"
}

Error Response (400)

JSON

{
  "error": "email is not a valid email address"
}

Example

curl

curl -X POST https://your-api-url.com/api/contact \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alice Smith",
    "email": "alice@example.com",
    "subject": "Question about your service",
    "message": "Hi, I have a question about pricing.",
    "product_name": "My Store",
    "product_website": "https://mystore.com"
  }'

📦 Send Batch Emails

Purpose: Send multiple emails efficiently in one request.

HTTP

POST /api/batch/contact

When to use:

Newsletter sending
Marketing campaigns
Bulk notifications
Mass email sending (up to thousands of emails)

Request Body (Array of emails)

JSON

[
  {
    "sent_to": "user1@example.com",
    "subject": "Welcome to our newsletter!",
    "message": "<h1>Thank you for subscribing to our newsletter.<\h1>",
    "product_name": "My Company"
  },
  {
    "sent_to": "user2@example.com",
    "subject": "Special offer just for you!",
    "message": "<h1>Get 50% off on all products this week.<\h1>",
    "product_name": "My Company"
  },
  {
    "sent_to": "user3@example.com",
    "subject": "Your order has been shipped",
    "message": "<h1>Your order #12345 is on its way!<\h1>",
    "product_name": "My Store"
  }
]

Field Descriptions

sent_to (required): Recipient's email address
subject (optional): Email subject (max 300 characters)
message (required): Email content in html format
product_name (optional): Sender name/company

Response

Server-Sent Events (SSE) stream showing real-time progress:

SSE

data: {"email":"user1@example.com","status":"success"}


data: {"email":"user2@example.com","status":"success"}


data: {"email":"user3@example.com","status":"failed","error":"invalid email address"}

Response Fields

email: The recipient email address
status: Either "success" or "failed"
error: Error message (only present if status is "failed")

Example

curl

curl -X POST https://your-api-url.com/api/batch/contact \
  -H "Content-Type: application/json" \
  -d '[
    {
      "sent_to": "customer1@example.com",
      "subject": "Thank you for your purchase",
      "message": "Your order has been confirmed!",
      "product_name": "Online Store"
    },
    {
      "sent_to": "customer2@example.com",
      "subject": "Welcome to our service",
      "message": "We are excited to have you on board!",
      "product_name": "Online Store"
    }
  ]'

📋 Data Models

ContactForm Model

JSON

{
  "name": "string (required, max 100 chars)",
  "email": "string (required, valid email, max 255 chars)",
  "subject": "string (required, max 300 chars)",
  "message": "string (required)",
  "product_name": "string (optional)",
  "product_website": "string (optional, valid URL)"
}

Email Model

JSON

{
  "sent_to": "string (required, valid email)",
  "subject": "string (optional, max 300 chars)",
  "message": "string (required)",
  "product_name": "string (optional)"
}

EmailResult Model

JSON

{
  "email": "string (recipient email)",
  "status": "string (success/failed)",
  "error": "string (optional error message)"
}

Monitoring

💚 Health Check

HTTP

GET /api/health

When to use:

Monitor your service status
Set up automated health monitoring
Check before sending important emails

Response Structure

JSON

{
  "status": "healthy",
  "timestamp": "2025-08-25T12:39:00Z",
  "version": "1.0.0",
  "checks": [
    {
      "name": "memory",
      "status": "healthy",
      "latency": "1.2ms"
    },
    {
      "name": "goroutines",
      "status": "healthy",
      "latency": "0.8ms"
    },
    {
      "name": "error_rate",
      "status": "healthy",
      "latency": "0.5ms"
    }
  ],
  "metrics": {
    "uptime": "24h30m",
    "request_count": 150,
    "error_count": 2,
    "error_rate": 1.33
  }
}

🔧 Runtime Information

HTTP

GET /api/runtime-info

Response Structure

JSON

{
  "go_version": "go1.21.0",
  "num_cpu": 2,
  "num_goroutine": 5,
  "gomaxprocs": 2,
  "memory": {
    "alloc_bytes": 2048576,
    "total_alloc_bytes": 5242880,
    "sys_bytes": 8388608,
    "heap_alloc_bytes": 2048576,
    "heap_sys_bytes": 4194304,
    "num_gc": 3,
    "gc_cpu_fraction": 0.001
  },
  "environment": {
    "aws_lambda_function_name": "FormMaillyGo",
    "aws_lambda_function_version": "1",
    "aws_region": "us-east-1"
  }
}

📊 Performance Metrics

HTTP

GET /api/metrics

Response Structure

JSON

{
  "uptime": "24h30m15s",
  "request_count": 1250,
  "error_count": 15,
  "error_rate": 1.2,
  "average_latency": "150ms",
  "min_latency": "50ms",
  "max_latency": "2s",
  "requests_per_second": 0.014,
  "emails_sent": 980,
  "emails_failed": 20,
  "email_success_rate": 98.0,
  "memory_usage_bytes": 2097152,
  "memory_peak_bytes": 4194304,
  "goroutines": 8,
  "goroutines_peak": 25,
  "cpus": 2,
  "go_version": "go1.21.0"
}

⚠️ Error Handling

Common HTTP Status Codes

200 OK: Request successful
201 Created: Email sent successfully
400 Bad Request: Invalid input data
500 Internal Server Error: Server error (email sending failed)
503 Service Unavailable: Service is unhealthy

Validation Errors

JSON

{
  "error": "email is not a valid email address"
}

Common validation errors:

"name is required"
"email is not a valid email address"
"subject must be less than or equal to 300 characters"
"message is required"

🛡️ Security Features

CORS Headers: Properly configured for cross-origin requests
Content Security Policy: Prevents XSS attacks
Input Sanitization: Cleans email headers to prevent injection
TLS Encryption: All SMTP communications use TLS
Rate Limiting: Built-in protection through AWS Lambda

📊 Performance & Scaling

Batch Processing Performance

Small batches (1-25 emails): Uses 1-2 workers
Medium batches (26-1000 emails): Uses optimal worker count based on CPU
Large batches (1000+ emails): Uses up to 25 workers for maximum efficiency

Memory Management

Uses object pools to reduce garbage collection
Monitors memory usage and alerts if limits are approached
Automatically optimizes for AWS Lambda constraints

🏁 Getting Started

Deploy FormMaillyGo to AWS Lambda
Configure environment variables (Gmail credentials, SMTP settings)
Test the service using the health endpoint
Integrate the API endpoints into your application
Monitor performance using the metrics endpoints

Happy emailing! 📧✨