cabanga/smail-service repository overview

⁠Smail (Simple Mail Service) - Email Microservice for Receiving Contact Form Submissions

Smail is a secure and configurable PHP email microservice designed to serve as the backend for contact forms on static websites (HTML/CSS/JS, VueJS, React, etc.). With a single implementation, it can support multiple websites without the need for a full backend.

This service was built with a focus on security, flexibility, and ease of implementation.

⁠Features

• Simple Integration: A single endpoint to receive form data via JSON.
• Centralized Configuration: All configurations (SMTP, emails, routes) are controlled through a .env file or Docker environment variables.
• Security:
  • CORS protection to restrict allowed domains.
  • Input validation, including conditional logic for required fields.
  • Sanitization of all inputs to prevent XSS.
  • HTML template purification to block malicious code.
• Dynamic Templates: Use the default email template or send fully custom HTML per request.
• Multilingual Responses: Returns success or error messages in the requested language (English and Portuguese by default, easily extendable).
• Logging: Logs successful submissions and errors in separate log files.
• Tested: Includes a PHPUnit test suite to ensure reliability.

⁠Installation & Deployment

1. Create a file named docker-compose.yml and paste the following content. Make sure to use the latest image version (or download it from the repository - https://github.com/delcioPHP/smail-service⁠).

version: '3.8'

services:
  smail-service:
    image: cabanga/smail-service:1.0.0
    container_name: smail-service
    ports:
      - "8080:80"
    restart: unless-stopped
    environment:
      # SERVICE
      - ALLOWED_ORIGINS=http://localhost:3000,http://yourdomain.ao
      - API_ROUTE=/api/contact
      - LOG_PATH=/var/www/html/logs/
      - DEFAULT_LANG=pt
      - API_SECRET_KEY=chave_super_secreta

      # SMTP
      - SMTP_HOST=smtp.yourdomain.ao
      - SMTP_PORT=465
      - [email protected]
      - SMTP_PASSWORD=SuaSenhaSuperSegura
      - SMTP_SECURE=ssl

      # E-mail
      - [email protected]
      - EMAIL_FROM_NAME="Contacto do Site"
      - [email protected]
      - EMAIL_SUBJECT="Novo Contacto do Website"

      # SECURITY  
      - RECAPTCHA_ENABLED=false  
      - RECAPTCHA_SECRET_KEY=''  
      - RECAPTCHA_V3_THRESHOLD='0.5'
      - RECAPTCHA_URL='https://www.google.com/recaptcha/api/siteverify'

1. Edit Environment Variables: Adjust the values in the environment: section to match your SMTP credentials, allowed domains, etc.

2. Start the Service: In the same folder where you saved the file, run:

docker-compose up -d