PHPackages                             cabanga/smail-service - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Mail & Notifications](/categories/mail)
4. /
5. cabanga/smail-service

ActiveProject[Mail & Notifications](/categories/mail)

cabanga/smail-service
=====================

An email microservice for contact forms || Um micro-serviço de e-mail para formulários de contacto.

v1.0.0(10mo ago)00PHPPHP >=8.1

Since Jun 22Pushed 10mo agoCompare

[ Source](https://github.com/delcioPHP/smail-service)[ Packagist](https://packagist.org/packages/cabanga/smail-service)[ Docs](https://github.com/delcioPHP/smail-service)[ RSS](/packages/cabanga-smail-service/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (4)Versions (2)Used By (0)

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

[](#smail-simple-mail-service---email-microservice-for-receiving-contact-form-submissions)

[![PHP Version](https://camo.githubusercontent.com/04744bae0a61d2ffe29c26f07a9612eae20445fc6feaeb77b3af1f0e9be6447c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d253345253344382e312d3838393242462e737667)](https://php.net/)[![License: MIT](https://camo.githubusercontent.com/fdf2982b9f5d7489dcf44570e714e3a15fce6253e0cc6b5aa61a075aac2ff71b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d79656c6c6f772e737667)](https://opensource.org/licenses/MIT)[![Docker Ready](https://camo.githubusercontent.com/7aa3db3a76815f8fcf908306a6362b4d888fb1666e3ca528782576d6da67b986/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f646f636b65722d72656164792d626c75652e737667)](https://www.docker.com/)![Tests](https://camo.githubusercontent.com/430da3cb56810cb8fd03334a2bca15ef6ec35d1e33103b20e735eae7ed6ad98c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7465737465732d70617373696e672d627269676874677265656e2e737667)

**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
--------

[](#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
------------

[](#requirements)

- PHP >= 8.1
- [Composer](https://getcomposer.org/)
- [Docker](https://www.docker.com/) (Recommended for deployment)

Installation & Deployment
-----------------------------

[](#installation--deployment)

### With Docker (Recommended)

[](#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).

```
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
      - SMTP_USERNAME=no-reply@yourdomain.ao
      - SMTP_PASSWORD=SuaSenhaSuperSegura
      - SMTP_SECURE=ssl

      # E-mail
      - EMAIL_FROM=no-reply@yourdomain.ao
      - EMAIL_FROM_NAME="Contacto do Site"
      - EMAIL_TO=your@yourdomain.com
      - 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'
```

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:

```
docker-compose up -d
```

4. **Check if it works:** The service should now be accessible at `http://localhost:8080`.
5. To stop the service, run:

```
docker-compose down
```

### Manual Installation

[](#manual-installation)

1. **Clone the repository:**

```
git clone https://github.com/delcioPHP/smail-service
cd smail-service
```

2. **Install dependencies:**

```
composer install --no-dev --optimize-autoloader
```

3. **Configure the environment:**

```
cp .env.example .env
```

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

[](#manual-via-composer)

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

```
composer create-project cabanga/smail-service smail-service
```

Usage (Service)
---------------

[](#usage-service)

### Endpoint

[](#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)

[](#request-body-json)

#### Basic Use

[](#basic-use)

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

```
{
  "name": "Kubanza Nzagi Afric",
  "email": "kubanza.nzagi@cliente.com",
  "recaptchaToken": "token",
  "company": "Empresa Fantástica Lda",
  "query": "Olá, gostaria de pedir um orçamento para o vosso serviço.",
  "websiteUrl": ""
}
```

#### Advanced Use

[](#advanced-use)

Allows customized behavior.

```
{
  "lang": "en",
  "websiteUrl": "",
  "recaptchaToken": "token",
  "name": "Kubanza Nzagi Afric",
  "email": "kubanza.nzagi@client.com",
  "phone": "555-1234",
  "subject": "Urgent Quote Request",
  "required_fields": ["name", "email", "subject"],
  "html_template": "New Lead: {{subject}}From: {{name}} ({{email}}).Phone: {{phone}}"
}
```

- `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

[](#api-responses)

#### Success (200 OK)

[](#success-200-ok)

`en:`

```
{
  "success": true,
  "message": "Message sent successfully!"
}
```

`pt:`

```
{
  "success": true,
  "message": "Mensagem enviada com sucesso!"
}
```

#### Error (4xx or 5xx)

[](#error-4xx-or-5xx)

`en:`

```
{
  "success": false,
  "message": "The field email is required"
}
```

`pt:`

```
{
  "success": false,
  "message": "O campo email é obrigatório"
}
```

- **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

[](#javascript-example)

```
const apiKey = 'chave_super_secreta';

fetch('https://api.seusite.com/api/contact', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': apiKey
  },
  body: JSON.stringify({
    name: "Kubanza Nzagi Afric",
    email: "kubanza@afric.ao",
    query: "A minha mensagem segura.",
    recaptchaToken: "token",
    websiteUrl: ""
  })
})
.then(res => res.json())
.then(data => console.log(data));
```

### CRITICAL SECURITY WARNING

[](#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
-------

[](#license)

This project is licensed under the MIT License.

WARNING: Modifications require authorization.

###  Health Score

28

—

LowBetter than 54% of packages

Maintenance54

Moderate activity, may be stable

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity45

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

329d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/4d6aae00e78aa52cd5ab12ab38ad0e7d075f94f8f3b40d52477a6f490dc5b2d1?d=identicon)[delcio](/maintainers/delcio)

---

Top Contributors

[![delcioPHP](https://avatars.githubusercontent.com/u/15670746?v=4)](https://github.com/delcioPHP "delcioPHP (9 commits)")

---

Tags

phpapismtpMicroservicephpmailercontact form

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/cabanga-smail-service/health.svg)

```
[![Health](https://phpackages.com/badges/cabanga-smail-service/health.svg)](https://phpackages.com/packages/cabanga-smail-service)
```

###  Alternatives

[jason-munro/cypht

Lightweight Open Source webmail written in PHP and JavaScript

1.5k146.0k](/packages/jason-munro-cypht)[ivantcholakov/codeigniter-phpmailer

A CodeIgniter 3 compatible email-library powered by PHPMailer.

25313.9k](/packages/ivantcholakov-codeigniter-phpmailer)[hafael/azure-mailer-driver

Supercharge your Laravel or Symfony app with Microsoft Azure Communication Services (ACS)! Effortlessly add email, chat, voice, video, and telephony-over-IP for next-level communication. 🚀

14109.2k](/packages/hafael-azure-mailer-driver)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)