NullSablex/email-samp

email_samp

SMTP mail plugin for SA-MP and Open Multiplayer, written in Rust — by NullSablex

Overview

email_samp sends email straight from the server — registration codes, password resets, staff alerts — with no PHP script, no external service and no abandoned plugin in between. It speaks SMTP itself, over TLS, and every call returns immediately: the mail leaves on a worker thread and reports back through a Pawn callback.

The same binary loads on SA-MP and on Open Multiplayer — natively as a component (recommended) or via legacy mode.

Not affiliated. This is an independent, community-maintained project. It is not affiliated with, endorsed by or sponsored by SA-MP, the open.mp (Open Multiplayer) project, or any email provider named in the documentation. Those names belong to their owners and appear here only to describe what this plugin works with.

Highlights

• Zero external dependencies — no PHPMailer, no sendmail, no OpenSSL. SMTP and TLS (via rustls) are compiled into the binary.
• Nothing blocks. Sends run on a pool of worker threads, so the server keeps ticking while a slow relay takes its time.
• Configuration from one place — a .env (through env_samp), the process environment, an SMTP URL or smtp.ini. One table of keys, whichever source you pick.
• Mail from a file — a .tpl carrying subject, text and HTML, or a plain .html like the ones you already send from PHP, with {markers} filled in from the gamemode. Edit the file and the next mail uses it, with no restart.
• Paced for real providers — messages per minute, priorities, retries on temporary failures, and a queue limit that refuses a send on the calling line instead of growing without bound.
• Accented names arrive intact — Pawn's 8-bit strings are read as the server's code page (charset), not assumed to be UTF-8.
• Safe with player input — line breaks in headers are refused, addresses are parsed, template values are HTML-escaped, and attachments cannot escape the server folder.
• Visible from the gamemode — email_stats says how many mails are waiting, sent and failed; email_limit reports the limits the plugin enforces.
• A dry-run mode that writes each message to logs/dry-run/ as an .eml and sends nothing, for working on a gamemode without spending quota.

Installation

1. Download email_samp.so / email_samp.dll and the include from the latest release.
2. Put the include in your pawno/include (or qawno/include) folder.
3. Install the binary:
   • SA-MP — drop it into plugins/ and add it to server.cfg:

     plugins email_samp.so
     

     (or email_samp.dll on Windows)
   • Open Multiplayer (native, recommended) — drop the binary into components/. open.mp finds it on start; no config.json entry needed.
   • Open Multiplayer (legacy) — the same binary works as a legacy plugin: put it in plugins/ and add it to legacy_plugins in config.json.

Quick start

#include <a_samp>
#include <email_samp>

public OnGameModeInit()
{
    // Reads SMTP_* from the environment, or smtp.ini next to server.cfg
    if (!email_setup())
    {
        print("[email] mail is not configured");
        return 1;
    }

    email_send_to("[email protected]", "Welcome", "Your account is ready.");
    return 1;
}

With the settings in a .env, include <env_samp> first and call email_setup_env() instead: it reads smtp.host, smtp.user, smtp.password and the rest.

To know whether it worked, name a callback. The result comes first, then the values you listed:

email_send_to(address, "Welcome", body, "OnMailSent", "d", playerid);

Email::OnMailSent(success, playerid)
{
    SendClientMessage(playerid, -1, success ? ("Email sent.") : ("Email failed."));
    return 1;
}

Email:: ships with the include and is shorthand for the usual forward + public pair.

Documentation

Examples

Start with examples/00_ready_to_send.pwn: a complete gamemode where you fill in four lines with your SMTP details and can send, with the mail itself in 00_ready_to_send.tpl, ready to reword.

The rest of examples/ covers one question each — where to keep the password, HTML and attachments, templates, error handling, a /register flow with a confirmation code, and mailing every player. See the examples README.

Configuration

One table of keys, read the same way from every source — a .env through env_samp, the process environment, an SMTP URL, smtp.ini, or the settings string email_connect takes.

Three of them usually do:

host     = smtp.gmail.com
user     = [email protected]
password = "an app password"

The port follows from the encryption, which defaults to a required STARTTLS.

The rest are optional and cover the sender's identity (from, from_name, helo), the connection (port, encryption, timeout, pool_size, tls_ca, tls_verify, allow_plaintext_auth, charset), how fast mail leaves (retries, rate_limit, queue_limit) and dry_run; a single url can carry several at once. Configuration explains what each one does.

Keys are case-insensitive and an optional SMTP_ prefix is dropped, so SMTP_HOST, smtp_host and host are one key. An unrecognised key is an error, never a silent no-op: SMTP_PASSWD would otherwise look exactly like "no password configured".

Ready-made templates: env.example for a .env, smtp.ini.example for a file.

Building from source

Requirements

• Rust stable with the targets i686-unknown-linux-gnu and i686-pc-windows-msvc
• cargo-xwin for cross-compiling the Windows .dll from Linux (installed by the script)
• 32-bit C support for the Linux target: the TLS backend (ring) compiles C and 32-bit assembly, so gcc -m32 must work — apt install gcc-multilib g++-multilib on Debian/Ubuntu, glibc-devel.i686 on Fedora, lib32-glibc on Arch
• LLVM, only when cross-compiling the Windows .dll from Linux
• No system mail or TLS libraries

Build

./scripts/build-linux.sh              # Linux .so + Windows .dll
./scripts/build-windows.sh            # from Windows
PROFILE=dev ./scripts/build-linux.sh  # development build

Security

• TLS is required, not optional. STARTTLS must succeed or the send fails; an attacker who strips it gets a failed mail, not a plaintext password.
• The trust store is compiled in (webpki roots), not the system's. Public providers work unconfigured; a relay with a private CA needs tls_ca.
• Header injection is refused, not sanitised. A line break in a subject, display name, address or custom header would add a header — a hidden Bcc: on a password-reset mail — so the value is rejected.
• Template values are HTML-escaped in the [html] part, so a nickname containing <script> arrives as text.
• Files stay in the server folder. Attachments, embedded images and templates are resolved and refused if they leave it or go through a symlink, so a path built from player input cannot mail out server.cfg.
• Plaintext credentials take an explicit opt-in. Sending the password unencrypted to a host other than this machine is refused unless allow_plaintext_auth=1; a relay on localhost is allowed with a warning.
• The password reaches no log at all — it goes to the SMTP client and nowhere else. What logs/email.log keeps, and the console is spared, is the rest of the detail: a recipient's address, the relay's own reply.
• Keep smtp.ini and .env out of version control.

Contributing

Bug reports, questions and pull requests are welcome — see CONTRIBUTING.md for how the project is built and what a change has to satisfy. Participation follows the Code of Conduct.

Found a security vulnerability? Please report it privately: SECURITY.md.

License

This project is distributed under the GNU General Public License v3.0. You can use, modify and redistribute it freely, provided derivative works are released under the same license with source code available.