AI-Mailer User Guide

Requirements

Before installing, make sure your hosting has PHP 8.1 or newer (8.2 recommended), MySQL 5.7+ (or MariaDB equivalent), the sodium PHP extension (used for offline license verification), and outbound SMTP access on the port your mail provider uses (commonly 587).

Running the installer

Upload the application folder to your hosting and open install/index.php in a browser. The wizard walks through four steps:

1. 1
   Requirements check — confirms the PHP version, required extensions (including sodium) and that the application folder is writable where needed.
2. 2
   Database connection & table prefix — enter your MySQL host, database name, user and password, and the table prefix to use (aim_ by default). The installer creates every table from its bundled migrations.
3. 3
   Admin account — create the first Super Admin user: name, email and password.
4. 4
   Finish — the installer writes config.php and shows a link to the login page. Delete the install/ folder (or restrict access to it) once installation is confirmed working.

First login & license

Log in with the admin account created during installation. The app runs on the Free tier until a license key is entered — go to Settings → License (Admin only), paste your key and save. The key is verified completely offline, against the domain the app is running on and its expiry date; nothing about your installation or key is ever sent anywhere for this check. A missing, invalid or expired key never blocks the app — it simply behaves as the Free tier. See License tiers for what each tier unlocks.

Senders & SMTP servers

SMTP is the protocol one mail server uses to hand an email to another — it is the real mechanism behind every message AI-Mailer sends. Clicking “send campaign” does not deliver email by itself: the app connects to the SMTP server you configured (host, port, encryption, login and password) and that server relays the message onward.

Under Senders you define the “From” name and address shown to recipients; under SMTP servers you define the actual connection credentials used to send. A campaign is not limited to a single SMTP server — you can select several active servers, and the sending engine rotates between them while working through the recipient queue. This matters because every provider enforces its own limits (Gmail, for instance, caps the number of emails per day per account):

• Limit per hour / per day — 0 means no limit. Once a server hits its limit, the sending engine skips it for the rest of that period and continues through another server still in rotation; recipients are never marked as “failed”, only held back until the limit clears.
• Delay between sends — a pause, in seconds, between messages sent through that particular server, useful for providers that throttle by rate rather than daily volume.
• Order — decides which server rotation tries first among the ones selected for a campaign; lower numbers go first.

Templates

Build reusable message templates with a code editor (CodeMirror) that shows a live preview alongside the HTML/CSS you write, or start from one of the bundled predefined templates and adjust it. Keep in mind that most email clients strip <style> blocks and ignore JavaScript entirely, so styling is applied inline and templates are built accordingly — this also makes rendering in Outlook and other quirky clients predictable.

Importing recipients

Recipients can be added in several ways, and all of them share the same tagging and custom-field model:

• CSV / XLSX import — Recipients → Import auto-detects column headers in both English and Polish (email/e-mail, first_name/imię, status, tags and custom-field columns). Only a missing or invalid email fails a row; every other issue is handled gently so one bad row doesn't block the whole file. A summary reports how many rows were added, updated or skipped.
• Quick paste — paste a plain list of addresses directly, without preparing a file.
• Import Bridge — pulls recipients straight from an existing external MySQL table, such as a subscriber table already maintained by a WordPress or Joomla site, or any other system with its own MySQL database. It is a generic database connection, not a platform-specific plugin: name the connection, enter host/port/database/table/credentials (the password is encrypted before it's stored), test the connection, map which column is the email and which is the name, choose a duplicate-handling mode and which tags to assign, then run it. Each recipient brought in this way is tagged with the bridge that imported it, the same way a CSV import or signup form records its own source.
• Tags — segmentation works through tags rather than fixed mailing lists, so one recipient can belong to as many groups as needed.

Creating & sending a campaign

A campaign picks a template, one or more sender/SMTP combinations, and a recipient selection by tag. Four different triggers drive the exact same underlying sending engine — use whichever fits your workflow, or mix them across campaigns:

All four ultimately call the same batch-processing engine, so a queued campaign can be picked up and continued by any of them — starting a send with “Send now” and closing the tab doesn't lose progress if a cron trigger is also configured; it simply continues from where sending stopped.

Signup widgets & double opt-in

The Subscribe Widget designs an embeddable public signup form, hosted entirely on your own website — AI-Mailer generates a plain, self-contained <form> with inline styles (not a <script> loader), so it works even inside page builders that strip script tags from pasted HTML blocks, and has no CORS concerns since the browser submits it directly. Each widget has its own name, optional first/last-name fields with their own placeholders, a label and button color, and one or more tags automatically assigned to anyone who signs up through it. The edit screen shows a live preview and a ready-to-copy embed snippet, generated the moment you start creating the widget:

<form method="post" action="https://your-domain.example/index.php?component=subscribe&action=submit" style="max-width:360px;font-family:sans-serif;">
  <input type="hidden" name="widget" value="your-widget-public-key">
  <div style="position:absolute;left:-9999px;" aria-hidden="true">
    <label>Leave this field empty<input type="text" name="website" tabindex="-1" autocomplete="off"></label>
  </div>
  <input type="email" name="email" placeholder="Your email address" required style="width:100%;padding:10px;margin-bottom:8px;border:1px solid #ccc;border-radius:4px;">
  <button type="submit" style="background:#0054a6;color:#fff;border:0;padding:10px 20px;border-radius:4px;cursor:pointer;">Subscribe</button>
</form>

The hidden website field is a honeypot — invisible to real visitors but attractive to simple bots — and every submission is also checked against the suppression list and blocked-IP list before being accepted.

Enabling double opt-in means a new submission is not added to the recipient list immediately — a confirmation email is sent, and the address only becomes a real, tagged recipient once that link is clicked. This requires an active SMTP server to send the confirmation email, so the checkbox is disabled (with an explanation) if no server is configured yet.

Reading your statistics

Open and click tracking works by rewriting the email's content at send time — an invisible 1×1 tracking pixel for opens, and every link swapped for a redirect address for clicks, both controlled by tracking checkboxes on the campaign form. The open pixel only fires if the recipient's mail client actually loads remote images, so true open rates are always somewhat higher than what's measured — a well-known, industry-wide limitation of pixel-based tracking, not something specific to this app. Click tracking is more reliable, since it only fires on a deliberate click.

Per-recipient open/click detail is visible on the campaign's own detail page; aggregated metrics — sends per day, by tag, by campaign, geographic map, device/browser breakdown — appear on the Statistics dashboard.

Suppression list & blocked IPs

The Blacklist screen has two independent tabs that are easy to confuse:

• Suppression list — email addresses and domains that must never receive a campaign, regardless of tags. Add a specific address or a whole domain with a wildcard pattern (e.g. *@example.com). It is checked both when a campaign starts and again at the moment each individual message is actually sent, so adding an address here stops future sends even to an already-queued campaign.
• Blocked IPs — a completely separate list of IP addresses (or patterns) barred from submitting the public signup form. This protects the widget from abuse and is unrelated to who may receive a campaign.

Both tabs support bulk-adding multiple entries at once through a text box, and both use simple wildcard (*) matching rather than regular expressions.

DKIM/SPF/DMARC & bounce handling

SPF, DKIM and DMARC are three independent, complementary mechanisms that tell a receiving mail server a message genuinely came from you, rather than someone spoofing your domain — together they account for much of whether a message lands in the inbox or in spam.

SPF and DKIM are worth configuring for every domain you send campaigns from — without them, Gmail and Outlook in particular increasingly route mail straight to spam. DMARC is an additional, useful step once SPF and DKIM are already working.

A bounce is a rejection notice sent back by the receiving server — address doesn't exist, mailbox full, and so on. Detecting it requires checking the actual mailbox bounces are returned to, so bounce handling needs its own credentials, separate from the ones used to send. On the SMTP server's Bounces tab: enable checking, fill in the host/port/protocol (IMAP or POP3) and folder of that mailbox, enter its login and password (a different account from the SMTP login above, typically something like bounce@yourdomain.com), and set how often it's checked. A detected hard bounce marks that recipient as “bounced” globally, across every tag, so future campaigns automatically skip them.

License tiers

AI-Mailer runs on three license tiers — Free, Basic and Full. Every tier can send real campaigns to real recipients through your own SMTP servers; the paid tiers add deliverability, reporting and automation extras on top. The license key is verified entirely offline; nothing about your installation or key is ever transmitted anywhere.

Included at every tier

Unlimited campaigns, recipients, tags and templates; SMTP sending through your own server(s); the visual template builder and code editor; signup widgets including double opt-in confirmation emails; and per-campaign sending progress, open/click tracking, and “sends per day” / “by tag” / “by campaign” reporting on the Statistics page.

Added by Basic and Full

Basic and Full unlock exactly the same feature set described above — there is no functional difference between them inside the app itself. The only difference is how many distinct domains one license key covers: a Basic key is tied to a single domain, a Full key covers up to 25. Choose whichever matches how many sites you plan to run AI-Mailer on — a single site (or several, each with its own Basic key) versus an agency bundle of up to 25 sites on one Full key.

Upgrade or purchase a license at shop.creativai.ai.

System requirements

• PHP 8.1 or newer (8.2 recommended)
• MySQL 5.7+ or an equivalent MariaDB version
• The sodium PHP extension (offline Ed25519 license verification)
• Outbound SMTP access from your hosting on the port your provider requires
• IMAP or POP3 access to a bounce mailbox, if you want automatic bounce handling

Folder structure for self-hosting

AI-Mailer ships as a single folder you upload to any subfolder of your hosting — there is nothing to move outside the webroot. Protection for sensitive files (config.php, migrations, logs) is handled with .htaccess rules shipped alongside them, not by relying on a special server layout.