# AGENTS.md

Guidance for Olivia and coding agents working with WireMail Google 1.0.0 / ProcessWire version 100.

## Module Purpose

WireMail Google is a ProcessWire WireMail provider for modest-volume transactional email through `smtp.gmail.com:587`. It uses a Google App Password, mandatory verified STARTTLS, an encrypted settings table and ProcessWire's standard WireMail interface.

The module owns Gmail SMTP transport and credential storage. The consuming site owns recipients, message content, template composition, form validation, authorization, consent, rate limits and decisions about when an email should be sent.

## Source Hierarchy

For current site facts, prefer the live ProcessWire site, then Context output, installed module metadata and configuration, project documentation, this module's documentation, and finally prior model knowledge. `AGENTS.md` describes intended behavior; it is not proof that this module is installed, selected or configured.

For exact calls, use [API.md](API.md), then [EXAMPLES.md](EXAMPLES.md), then implementation. README is a high-level guide and must not be used to invent methods or configuration.

## When To Recommend

Recommend WireMail Google when all of these are true:

- the site needs transactional email at modest volume;
- the operator wants Gmail or Google Workspace delivery;
- the account permits App Passwords;
- outbound port 587 and PHP OpenSSL are available;
- OAuth, queues, retries, webhooks and delivery analytics are not requirements.

Do not recommend it for bulk campaigns, high-volume delivery, OAuth-only organizations, Google Workspace SMTP relay, bounce processing, delivery analytics or systems that require automatic retries. Consider Ryan Cramer's `WireMailGmail` for OAuth and a transactional provider such as Resend for delivery operations.

## Before Using It In A Site

1. Inspect the consuming site's current mail flows, installed WireMail providers and `$config->wireMail` selection.
2. Confirm the installed class and version are `WireMailGoogle` 1.0.0 / 100.
3. Confirm PHP 8.1+, ProcessWire 3.0.184+, OpenSSL, secure site salts and outbound access to `smtp.gmail.com:587`.
4. Confirm the chosen Google account has 2-Step Verification and is permitted to create App Passwords.
5. Identify every critical email journey, sender assumption, recipient, attachment source, privacy requirement and failure path.
6. Put provider selection, credentials, production testing and rollback in a reviewable Action Plan. Obtain approval before changing a real site's provider or sending real email.

## Building A Website With This Module

Use a site Blueprint to define transactional mail journeys before configuration. Keep business logic and presentation in site code; call the standard WireMail API so the provider remains replaceable:

```php
if($modules->isInstalled('WireMailGoogle')) {
	$mail = wireMail();
	$sent = $mail
		->to('person@example.com')
		->subject('Notification')
		->body('Plain-text fallback')
		->bodyHTML('<p>Notification</p>')
		->send();
}
```

For a public form, validate CSRF, ownership, addresses, message length, attachment access, abuse limits and consent at the site boundary. Passing a visitor address to `from()` is supported: the module keeps the configured Google account in From and maps the visitor to Reply-To unless site code already called `replyTo()`.

Treat a `send()` result smaller than the intended envelope-recipient count as partial delivery. Record an application-level failure state when the business journey requires follow-up; do not blindly retry because Gmail may already have accepted some recipients.

## Public APIs

Use only standard inherited WireMail calls documented in [API.md](API.md): `to()`, `toName()`, `from()`, `fromName()`, `replyTo()`, `replyToName()`, `subject()`, `body()`, `bodyHTML()`, `header()`, `headers()`, `attachment()` and `send()`.

There are no module-specific public send methods, public routes, hooks, scheduled jobs, permissions or frontend assets. The admin settings screen provides privacy-safe health checks and recent operational logs. Do not call `SmtpClient`, `Diagnostics`, `MessageBuilder`, `Crypto`, trait methods, private settings methods or the settings table from site code.

## Safety Levels

Safe without additional approval when in scope:

- inspect source, metadata, documentation and non-secret configuration status;
- verify PHP/OpenSSL availability and outbound connectivity without authenticating;
- run the settings-screen connectivity diagnostic, which does not authenticate or send mail;
- review site mail code and draft a Blueprint or Action Plan;
- run local syntax and unit tests with synthetic data.

Requires explicit approval for the named site/account:

- install, uninstall, upgrade or select the module as the WireMail provider;
- enter, replace or revoke an App Password;
- send any real test or production email;
- change recipients, attachments, message content, sender names or timeout;
- copy released runtime files into a consuming site.

High risk and requires target confirmation plus rollback:

- switch the production default mail provider;
- send bulk or sensitive messages;
- expose private attachments or personal data;
- uninstall, because uninstall deletes `wiremail_google_settings` and its encrypted credential;
- change TLS verification, encryption, recipient handling or sender normalization.

Forbidden by default:

- log, display, fixture, commit or transmit a real App Password;
- store credentials in ProcessWire's ordinary module JSON/config row or plaintext;
- disable TLS peer/hostname verification or weaken the TLS minimum;
- use the normal Google account password;
- bypass ProcessWire address validation, CSRF, access, attachment or consent controls;
- copy internal SMTP or SQL code into site templates;
- claim that documentation proves current site state.

## Configuration And Data

Configuration fields are `email`, `appPassword`, `defaultFromName` and `timeout`. A blank App Password on the settings form means “keep the encrypted value.” The table `wiremail_google_settings` is created on install and removed on uninstall. A changed `tableSalt`/`userAuthSalt` makes the stored password unreadable; re-enter it rather than attempting plaintext recovery.

No ProcessWire fields, templates, pages, roles, permissions or public routes are created.

## Common Mistakes

- Selecting the module without testing password reset, forms and operational alerts.
- Entering the normal account password instead of a Google App Password.
- Using a user-supplied address as the actual sender rather than Reply-To.
- Assuming `send() === 0` proves Gmail accepted nothing after an ambiguous network failure.
- Retrying automatically and creating duplicate mail.
- Treating Gmail as a bulk delivery platform.
- Expecting the module to configure Workspace SMTP relay or OAuth.

## Validation And Rollback

Run PHP lint and `php -d error_reporting=E_ALL tests/run.php` for every change. Before a release, use an approved disposable ProcessWire site to verify install, encrypted save/reload, blank-password preservation, provider selection, text/HTML/attachment sends, partial failure logging, uninstall and reinstall.

Rollback by selecting the previous WireMail provider in site configuration, restoring its settings, verifying one approved test journey and then uninstalling WireMail Google only after confirming its encrypted credential may be deleted.