E-mail and notifications¶
PKIFactor notifies people by e-mail: requesters and teams about their certificates, approvers about requests to decide, owners of deployment targets about planned and failed deployments, administrators about the licence and the platform's own service certificates. E-mail is the only notification channel of this version; events also reach your SIEM through the audit trail (SIEM and syslog).
E-mail settings, templates and the queue are reserved for administrators.
Configure SMTP¶
In the Administration workspace, open System > Email Settings, panel SMTP Settings.
| Field | Content |
|---|---|
| Enable Email Notifications | Global switch. While it is off, nothing is queued |
| SMTP Host / Port | Your relay. 587 with STARTTLS, 465 with SSL |
| Use TLS (STARTTLS) / Use SSL | Choose one; never send in clear text |
| Username / Password | A dedicated sending account. The password is encrypted at rest; "(configured)" shows that one is stored, and leaving the field empty keeps it |
| From Email / From Name | The sender shown to recipients (default name PKIFactor) |
| Expiry Alert Days | Comma-separated days before expiry when alerts are sent, default 30, 14, 7, 1. The same values drive the expiration bands of the dashboard. An entry that is not a number resets the list to the default |
Click Save, then, in the Connection Test panel:
- Test SMTP checks the connection and authentication.
- Enter an address and click Send Test to send a real message.
Since version 1.8.29 the SMTP server's certificate and name are verified, with STARTTLS and SSL alike, against the trusted authorities of the host. A relay whose certificate comes from a private CA fails Test SMTP with a certificate error: give the relay a certificate from a CA the host trusts, or, for a laboratory, set SMTP_TLS_INSECURE=1 in .env to restore the previous behaviour (no verification).
A successful test does not guarantee delivery: declare the sending server in the SPF and DKIM records of the sender's domain, and check quarantine folders.
In the Oversight workspace, Fleet monitoring > Monitoring also probes the SMTP server (section SMTP / Email) and shows the queue counters.
Certificate notifications¶
| Template code | Sent when | Recipients |
|---|---|---|
cert_requested |
A request waits for approval (or for domain validation) | The requester and the team address |
approval_pending |
A new request, a renewal or a revocation request enters an organization's queue | The organization's active approvers (Approvals) |
cert_approved |
An approver approves the request (issuance follows) | The requester and the team address |
cert_rejected |
An approver rejects the request | The requester and the team address |
cert_issue_failed |
The authority fails to issue a request that was approved | The requester and the team address |
cert_issued |
A certificate is issued (directly, after approval, or by renewal) | The certificate's user and the team address |
cert_revoked |
A certificate is revoked | The certificate's user and the team address |
approval_override_notice |
An administrator approves or rejects in place of the approvers (Approvals) | The organization's other active approvers |
cert_expiring |
Expiry alert, once per step of Expiry Alert Days | The certificate's user and the team address |
cert_expiry_digest |
Daily digest of expiry alerts, when the digest is enabled (see below) | One message per recipient |
acme_cert_expiring |
An ACME certificate approaches expiry, more than 7 days before, and no renewal has been seen | The ACME account's contact and the profile's team address |
acme_no_renewal |
Same, 7 days or less before expiry | The ACME account's contact and the profile's team address |
For an ACME certificate whose account has no contact address, the alert goes to the profile's team address; failing that, to the managers of the organization, then to its approvers, and as a last resort to the administrators.
The team address (Team Email)¶
The team address that receives a copy of the certificate notifications is chosen as follows:
- the Team Email entered on the request. This field is mandatory in Requests > New Request; when the requester belongs to teams with a contact address, the field offers them, and is prefilled when there is only one. The address can be changed later from the certificate's page with Update team email;
- failing that, the profile's Team address for automated certificates (ACME, EST, SCEP, CMP), in its Email Notifications section. It serves certificates issued through a protocol, with no human requester, and is the last resort for alerts.
The copy to the team is not sent twice when the team address is the requester's own address.
Switches and language per profile¶
Each certificate profile controls its notifications in its Email Notifications section:
- Send notifications when: New certificate request, Certificate is issued, Certificate is about to expire, Certificate is revoked (all on by default). New certificate request also governs the rejection message; Certificate is issued also governs the approval and the issuance-failure messages. The New certificate request switch is offered when the profile is created;
- Notification Language: English, French, Spanish or Portuguese.
A message addressed to a person is written in that person's language (My Profile > Interface Language, which also offers German), and otherwise in the profile's language. The copy to the team address uses the profile's language.
The approval_pending and approval_override_notice e-mails are not governed by these switches: approvers are always notified when e-mail is enabled.
Expiry alerts¶
Once a day, PKIFactor looks for issued certificates that expire exactly at one of the Expiry Alert Days steps and sends one alert per certificate and per step. For an ACME certificate, no alert is sent when a renewal already exists. The alert says whether an automatic renewal and deployment is planned, or whether the certificate must be renewed by hand.
Daily digest. When the system setting expiry_digest_daily is true, the alerts for certificates requested through the portal are grouped into one message per recipient and per day (cert_expiry_digest) instead of one message per certificate. ACME alerts stay individual. This setting is off by default and is changed through the settings API (see below).
Subject prefix¶
Every subject starts with a prefix, [PKIFactor] by default. To tell instances apart (for example [PKI-PROD]), change the system setting email_subject_prefix through the settings API.
Other notifications¶
| Template code | Sent when | Recipients |
|---|---|---|
ct_alert |
A Certificate Transparency rule with the e-mail action matches | The addresses listed in the rule |
service_tls_renewed / service_tls_failed |
PKIFactor renewed one of its own service certificates, or failed to | The administrator who linked the profile, otherwise the first active administrator |
licence_quota |
The number of managed certificates crosses a threshold of the licence, then weekly while at or above 100 % (License) | The active administrators and the licence's contract contact |
licence_expiry |
The licence ends in 60, 30 or 7 days, then weekly once it has ended | The active administrators and the licence's contract contact |
deploy_digest, deploy_notice, deploy_event |
See Deployment notifications |
Templates¶
The system templates are created when the platform starts. From Email Settings, panel Email Templates, click Manage to open the list (name, code, subject, available variables, Active or Inactive). If the list is empty, click Initialize Default Templates (Initialize Templates on the settings page).
For each template you can:
- edit the Template Name, Email Subject, HTML Body and Plain Text Body (Jinja2 syntax; the variables available for the template are listed and can be copied with a click), and switch it Active or not, then Save Template;
- preview it with sample data (subject, HTML version and plain text version);
- Reset to Default to return to the system version.
An inactive template sends nothing: switching a template off is the way to silence one kind of message for the whole platform. Templates are rendered in a sandbox; a syntax error is reported at preview time.
Keep the plain text body: some clients and gateways display only that part. The logo is embedded in the message, so recipients load no external resource.
Edits apply to the English version
Each system template carries built-in French, German, Spanish and Portuguese translations. Your edits change the English text only: recipients who receive another language keep receiving the built-in translation.
The sending queue¶
Messages are queued and sent by a background worker every minute. A failed message is retried up to 3 times (after 1, 5 and 15 minutes), then marked failed. A message stuck in processing for more than 15 minutes (worker interrupted) is picked up again.
The Email Queue panel shows the counters (Pending, Sent, Failed, Total); View all opens the queue (the 50 most recent messages), filterable by status (All, Pending, Sent, Failed). Each line shows the recipient, subject, template, status (Pending, Processing, Sent, Failed with its retry count, Cancelled) and creation date; you can cancel a pending or failed message, and hover a failed one to read its error. Process Queue sends pending messages immediately.
Deployment notifications¶
These messages concern deployment targets. They use the system templates deploy_digest, deploy_notice and deploy_event, go through the sending queue, and are written in the platform's default language (System > Settings).
| Message | Sent when | Recipients |
|---|---|---|
Planned Deployments Notice (deploy_digest) |
Once a day, if at least one automatic renewal and deployment will fire within 7 days (DEPLOY_DIGEST_LOOKAHEAD_DAYS), or a certificate from an authority unknown to PKIFactor expires within 90 days (DEPLOY_FOREIGN_CA_LOOKAHEAD_DAYS) |
The target's Owner team address |
Renewal Advance Notice (deploy_notice) |
Same round, for each binding concerned | The e-mail subscribers of the binding |
Deployment Event (deploy_event) |
A change made outside PKIFactor is found on the device or holds a deployment, a deployment fails on the device or waits for a manual installation step, or a renewal stuck in progress is restored | The target's Owner team address |
The digest gives advance notice and a veto window: to object, pause the binding before the planned date. Replies go to DEPLOY_OPPOSITION_EMAIL when set, otherwise to the From Email address. Empty digests are not sent.
Binding subscribers can be declared with the e-mail, webhook or SFTP channel, but only e-mail subscribers are notified in this version.
Via the API
# Routes without /api prefix: called under /api/v1/
curl -s -b jar https://clm.example.com/api/v1/admin/email/settings
curl -s -b jar -X POST https://clm.example.com/api/v1/admin/email/settings \
-H 'Content-Type: application/json' \
-d '{"smtp_host": "smtp.example.com", "smtp_port": 587, "smtp_username": "pkifactor@example.com",
"smtp_password": "...", "smtp_from_email": "pkifactor@example.com", "smtp_from_name": "PKIFactor",
"smtp_use_tls": true, "smtp_use_ssl": false, "enabled": true, "expiry_alert_days": [30, 14, 7, 1]}'
curl -s -b jar -X POST https://clm.example.com/api/v1/admin/email/test
curl -s -b jar -X POST https://clm.example.com/api/v1/admin/email/test-send \
-H 'Content-Type: application/json' -d '{"recipient": "me@example.com"}'
curl -s -b jar "https://clm.example.com/api/v1/admin/email/queue?status=FAILED"
curl -s -b jar https://clm.example.com/api/v1/admin/email/queue/stats
curl -s -b jar -X POST https://clm.example.com/api/v1/admin/email/queue/process
curl -s -b jar -X DELETE https://clm.example.com/api/v1/admin/email/queue/42 # cancel a message
curl -s -b jar https://clm.example.com/api/v1/admin/email/templates
curl -s -b jar -X POST https://clm.example.com/api/v1/admin/email/templates/init
curl -s -b jar -X POST https://clm.example.com/api/v1/admin/email/templates/7/preview
curl -s -b jar -X POST https://clm.example.com/api/v1/admin/email/templates/7/reset
# Subject prefix and daily digest (system settings)
curl -s -b jar -X PUT https://clm.example.com/api/v1/admin/settings \
-H 'Content-Type: application/json' \
-d '{"settings": {"email_subject_prefix": "[PKI-PROD]", "expiry_digest_daily": "true"}}'
smtp_password (or send it empty) to keep the stored password. A template is changed with PUT /admin/email/templates/{id} (name, subject, body_html, body_text, is_active).
Troubleshooting¶
| Symptom | Cause and fix |
|---|---|
| Nobody receives anything | Enable Email Notifications is off, or the queue shows failures. Open the queue, read the error of a failed message |
| Test SMTP fails | Wrong host, port or TLS mode (STARTTLS on 587, SSL on 465), or wrong credentials. Many providers require an application password |
Test SMTP fails with CERTIFICATE_VERIFY_FAILED |
The relay's certificate is not trusted by the host, or does not carry the host name entered (since 1.8.29). Use the relay's exact name, or a certificate from a trusted CA |
| Test e-mail sent but not received | Delivery problem: SPF, DKIM, quarantine on the recipient side |
| Approvers are not notified | No approver is assigned to the organization, the approver's account is inactive, or the approval_pending template is inactive. Deputies (delegations) are not notified by e-mail |
| The team does not receive notifications | No Team Email on the request and no team address in the profile, or the corresponding switch is off in the profile |
| A kind of message is never sent | Its template is Inactive in Email Templates |
| An edited template is not used | The recipient receives another language (their own interface language, or the profile's notification language): your edit changed the English version only |
| Messages stay pending | The background worker is not running. Click Process Queue and check the backend logs |
| No deployment digest | No renewal is planned within the window (empty digests are not sent), the target has no Owner team address, or e-mail is disabled |