Email setup

Pragma CMS includes a built-in SMTP engine to handle transactional emails such as password resets, notifications, and contact forms.

SMTP Configuration

Before Pragma CMS can send emails (forms, password resets, notifications), you must connect it to a professional SMTP provider. We recommend services like Postmark, SendGrid, Brevo, or Mailgun for maximum reliability.

Connection Settings

Go to your Site Settings in the Admin panel and fill in your SMTP information.

Example with Gmail:

smtp_host : smtp.gmail.com
smtp_port : 465
smtp_user : [email protected]
smtp_password : YOUR_APP_PASSWORD
smtp_encryption : ssl

info

Gmail Users: Generate an “App Password” for Gmail

Google no longer allows using your regular account password for third-party applications. You must create a dedicated app password:

Enable 2-Step Verification on your Google account if it’s not already active.
Go to the App Passwords page of your Google account: https://myaccount.google.com/apppasswords
Under “Your app passwords”, create a new entry named “Pragma CMS”.
Click “Create”.
Google will generate a 16-character password (e.g., abcd efgh ijkl mnop).

Copy this password WITHOUT spaces and paste it into the CMS settings under “SMTP password”.

Email Branding & Visuals

Pragma CMS uses a unified branding system. All outgoing emails automatically inherit your visual identity, ensuring a professional look without manual styling.

Global Branding Inheritance

The transactional email engine pulls data from your global Branding Settings:

Primary & Secondary Colors: Used for primary action buttons (CTA), links, and decorative borders.
Main Logo: The standard logo used in the header of all emails.
Inverse Logo: A fallback logo used automatically if your email template uses a dark header or background.

Email-Specific Customization

In the Email Settings panel, you can further refine the look of your communications:

Email Header Image: A specific banner image (Media ID) displayed at the very top of your emails, ideal for brand reinforcement.
Email Contact Address: A specific support or contact email address displayed in the footer for your users.
Email Footer Text: Custom rich text (e.g., company address, legal mentions, social links) that appears at the bottom of every message.
Email Background Color: Defines the global background color of all transactional emails. By default, emails use a white background (#ffffff), but this setting allows subtle customization to better match brand identity or improve readability in dark-themed designs.

Email Templates

Emails are rendered using a decoupled template system. Templates consist of two parts: an HTML version for modern clients and a Plain Text version for accessibility and spam score reduction.

Template Locations

The system looks for email templates in the following order:

themes/[your-theme]/templates/emails/
extensions/[extension-name]/resources/emails/
cms-versions/[version]/system/templates/emails/ (System defaults)

How to override a template

To customize the "Password Reset" or "Form Notification" email, copy the corresponding .html.php file from the core into your theme folder and modify the HTML/CSS.

Deliverability (SPF, DKIM & DMARC)

lightbulb

Crucial Step

Even with a correct SMTP configuration, your emails might land in SPAM if your domain is not authenticated.

To maximize your email deliverability, it is essential to configure SPF, DKIM, and DMARC records for your sending domain.

These authentication protocols ensure that your emails reach your recipients’ inbox instead of being flagged as spam. Proper configuration is critical for reliable email delivery.

These settings must be configured with your domain provider (where you purchased your domain name such as .com, .fr, etc., e.g., GoDaddy, OVH, Cloudflare). You will need to add TXT DNS records.

Your email service provider (Gmail, SendGrid, etc.) will provide the exact values to copy and paste. Here are setup guides for the most common services:

Google Workspace (Gmail): https://support.google.com/a/topic/9061731
SendGrid: https://docs.sendgrid.com/ui/account-and-settings/how-to-set-up-domain-authentication
Mailgun: https://documentation.mailgun.com/en/latest/user_manual.html#verifying-your-domain
Brevo (formerly Sendinblue): https://help.brevo.com/hc/en-us/articles/200227182-How-to-set-up-SPF-DKIM-and-DMARC-records