Download the PHP package cabanga/smail-service without Composer

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.
• Docker Ready: Comes with a docker-compose.yml for instant and isolated deployment.

Requirements

• PHP >= 8.1
• Composer
• Docker (Recommended for deployment)

Installation & Deployment

With Docker (Recommended)

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).

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

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

4. Check if it works: The service should now be accessible at http://localhost:8080.

5. To stop the service, run:

Manual Installation

1. Clone the repository:

2. Install dependencies:

3. Configure the environment:

Edit the .env file with your custom configuration.

4. Configure Web Server:

Point the root of your web server (Apache, Nginx) to the /public folder. Make sure URL rewrites (mod_rewrite) are enabled.

Manual via Composer

Using Composer, just run one command and follow up with web server setup:

Usage (Service)

Endpoint

• URL: [YOUR_DOMAIN] + [API_ROUTE] (e.g. http://localhost:8080/api/contact)
• Method: POST
• Headers: Content-Type: application/json and 'X-API-Key': apiKey

Request Body (JSON)

Basic Use

Uses the default email template. The query field is required.

Advanced Use

Allows customized behavior.

• lang (optional): Sets the API response language. Values: "en", "pt".
• html_template (optional): An HTML string for the email body. If used, query is not required. Use {{field_name}} placeholders.
• required_fields (optional): Array of fields that must be present in this request.

API Responses

Success (200 OK)

en:

pt:

Error (4xx or 5xx)

en:

pt:

• 400 Bad Request: Missing data, invalid JSON.
• 403 Forbidden: Unauthorized domain access.
• 404 Not Found: Endpoint not found.
• 405 Method Not Allowed: Incorrect HTTP method.
• 500 Internal Server Error: Internal failure (e.g. wrong SMTP credentials).

JavaScript Example

CRITICAL SECURITY WARNING

The API key should NEVER be hardcoded directly in your public JavaScript file. Anyone can view the source code and steal it.

Best practice? Inject the key into your frontend using client-side environment variables. Your build process should then securely make it available to your JavaScript.

To further enhance security, you may enable Google reCAPTCHA. Smail supports it out-of-the-box.

Examples:

• process.env.VUE_APP_API_KEY (Vue.js)
• process.env.REACT_APP_API_KEY (React)

License

This project is licensed under the MIT License.

WARNING: Modifications require authorization.