Skip to main content

Email Alerts

Extendy GeoShield can send a security alert email after a completed WHMCS client-area login has been logged and evaluated.

An alert email represents an evaluated login event. It does not mean that Extendy GeoShield blocked, approved, reversed, or prevented the WHMCS login. The addon is notification-only in the MVP.

When an email may be sent​

Extendy GeoShield attempts to send an alert email only when the login event and alert decision meet the current send rules.

The event must:

  • have a safely resolved Client Account context;
  • have decision_result = alert_required;
  • have alert_sent = false;
  • use one of the Extendy GeoShield alert template names;
  • have a valid primary WHMCS Client Profile email address available;
  • use an Extendy GeoShield email template that has no copied recipients configured.

If these conditions are not met, the event may still be logged, but email sending is skipped.

For how alert_required is determined, see Alert Modes.

Recipient behaviour​

For the MVP, Extendy GeoShield sends alert emails through WHMCS SendEmail using the safely resolved Client Account context.

The intended recipient is the primary email address on the WHMCS Client Profile for that Client Account.

The WHMCS User email that performed the login is included in the email content as the login actor. It is not used as the direct MVP email recipient.

If no safe Client Account context is available, Extendy GeoShield does not guess a recipient. It does not silently send to another Client Account, Contact, or additional copied recipient.

Alert modes and trusted countries​

Email alerts are driven by the configured Alert Mode and the evaluated country context.

At a high level:

  • Notify on Every Login can alert for each detected login country, subject to country-detection failure and cooldown rules.
  • Outside Trusted Countries can alert when the detected country is outside the trusted-country model for the event.
  • Smart Mode can alert when the detected country is new for the WHMCS User and Client Account context.

Trusted-country logic can suppress alerts in modes that evaluate trusted countries. Smart Mode known-country logic is scoped to the exact user/client context.

For details, see Trusted Countries and Smart Mode.

Country detection failure​

If Extendy GeoShield cannot determine the login country, it follows the Alert When Country Detection Fails setting.

  • No — the event is logged, but no client email is sent only because country detection failed.
  • Yes — the normal login alert template is used with Unknown country values.

Smart Mode trust links are not generated for Unknown country or country-detection failure alerts.

Only eligible Smart Mode new-country alerts can include a trust_country_url.

Trust links:

  • require WHMCS authentication before a country can be trusted;
  • are bound to the relevant WHMCS User and Client Account context when available;
  • expire after approximately 48 hours;
  • are one-time use;
  • do not trust a country merely because the email was received or opened.

Generic login alerts and Unknown country alerts keep the trust URL empty.

For the full trust-link behaviour, see Smart Mode.

Send failure behaviour​

Extendy GeoShield does not guarantee email delivery. Delivery still depends on WHMCS, the configured mail transport, and the recipient mailbox environment.

When WHMCS SendEmail reports failure, is aborted, or cannot be used safely, Extendy GeoShield keeps alert_sent = false and stores a safe failure reason in the login event where possible.

Examples of safe skip or failure conditions include:

  • no safe Client Account context;
  • no valid primary Client Profile email;
  • copied recipients configured on an Extendy GeoShield alert template;
  • SendEmail failure or abort;
  • controlled internal SendEmail error.

The addon also writes safe WHMCS Activity Log entries for selected email failure or skipped-recipient cases. These entries do not include provider credentials, raw provider responses, raw trust tokens, request headers, cookies, sessions, or database credentials.

The addon does not retry indefinitely.

Language behaviour​

The current implementation creates and uses WHMCS General email template records for the master/default language row.

Extendy GeoShield does not implement its own email language selector. It does not currently create Arabic or other localised email template rows automatically.

Administrators should review the generated WHMCS templates before production use and manage any WHMCS-side template localisation according to their WHMCS email template workflow.

What alert emails do not do​

Alert emails do not:

  • block login;
  • prove the visitor’s identity;
  • prove that an IP address is safe;
  • trust a Smart Mode country automatically;
  • send to Contacts or copied recipients silently;
  • include provider credentials or raw provider responses;
  • expose raw trust tokens except as the usable trust link where applicable.

For the exact template variables, see Email Templates and Variables.