# WireMail Google API

Public API reference for WireMail Google 1.0.0 / ProcessWire version 100.

## Compatibility

- Class: `ProcessWire\WireMailGoogle`
- Extends: `ProcessWire\WireMail`
- ProcessWire: 3.0.184+
- PHP: 8.1+
- Transport: `smtp.gmail.com:587`, STARTTLS, TLS 1.2+
- Authentication: complete Google account address plus 16-character App Password

The module intentionally adds no provider-specific public sending methods. Site code should depend on ProcessWire's WireMail contract.

## Obtain A Mailer

Use the provider selected for the site:

```php
/** @var WireMail $mail */
$mail = wireMail();
```

Feature-detect and request this provider explicitly only when the integration is intentionally Google-specific:

```php
if($modules->isInstalled('WireMailGoogle')) {
	/** @var WireMailGoogle $mail */
	$mail = $modules->get('WireMailGoogle');
}
```

## Supported Public Calls

These inherited WireMail calls are supported:

```php
$mail
	->to('person@example.com', 'Person')
	->toName('person@example.com', 'Updated name')
	->from('form-submitter@example.org', 'Form submitter')
	->fromName('Visible sender name')
	->replyTo('replies@example.org', 'Replies')
	->replyToName('Reply recipient')
	->subject('Subject')
	->body('Plain text')
	->bodyHTML('<p>HTML body</p>')
	->header('Cc', 'copy@example.com')
	->header('Bcc', 'audit@example.com')
	->header('X-Example', 'value')
	->headers(['X-Category' => 'transactional'])
	->attachment('/absolute/path/document.pdf', 'document.pdf');

$accepted = $mail->send();
```

`send()` returns the number of unique envelope recipients accepted by Gmail or `0` when delivery does not reach Gmail's acceptance response. To, CC and BCC recipients are included in the count. A return value between zero and the intended count means partial recipient acceptance.

Do not implement an automatic retry solely from this return value. A connection loss around Gmail's final acceptance response can be ambiguous, and retrying may duplicate a message.

## Address Behavior

### To

`to()` accepts the forms supported by ProcessWire WireMail, including a single address, comma-separated addresses, indexed arrays and `email => name` arrays. At least one To recipient is required.

### CC And BCC

Provide CC and BCC with `header('Cc', ...)` and `header('Bcc', ...)`. Both enter the SMTP envelope. BCC is deliberately omitted from rendered message headers.

### From And Reply-To

The configured `email` is always used in the MIME From header and SMTP envelope. When site code passes a different address to `from()` and has not set `replyTo()`, that address and name become Reply-To. An explicit `replyTo()` takes precedence.

The visible sender name comes from a per-message `fromName()`/`from(..., $name)` value first, then the configured `defaultFromName`.

## Body And Attachments

- `body()` produces a UTF-8 quoted-printable plain-text part.
- `bodyHTML()` produces a UTF-8 quoted-printable HTML part and a generated plain-text fallback when `body()` is empty.
- Supplying both creates `multipart/alternative`.
- Attachments create `multipart/mixed`, use detected MIME types when available and are base64 encoded in 76-character lines.
- Attachment paths must exist and be readable when the message is built.

Headers and filenames are normalized to prevent CR/LF header injection. Unicode display names and subjects use RFC 2047 encoding.

## Configuration

Configuration is managed through ProcessWire's module settings screen:

| Setting | Type | Default | Behavior |
|---|---|---:|---|
| `email` | Email | empty | Required SMTP username and sender address |
| `appPassword` | Password | empty | Required 16-character App Password; blank on later saves preserves the current encrypted value |
| `defaultFromName` | Text | empty | Optional fallback sender display name |
| `timeout` | Integer | `30` | Socket timeout clamped to 5–120 seconds |

The App Password is encrypted before storage in `wiremail_google_settings`. The settings table is an implementation detail and must not be queried or edited by site code.

## Errors And Logging

Missing configuration, invalid addresses, MIME errors, connection failures, certificate/TLS failures, authentication failures and SMTP rejection produce a ProcessWire error notice, write a sanitized entry to `wire-mail-google`, and return `0` unless Gmail already accepted at least one recipient.

Authentication commands and the App Password are never written to the log. RCPT rejection of one address does not prevent delivery to other accepted recipients.

The module settings screen includes read-only environment checks, an explicit Gmail connectivity check and a bounded view of the `wire-mail-google` log. Connectivity diagnostics verify DNS, port 587 and certificate-validated STARTTLS without authenticating. Operational log entries omit addresses, subjects, bodies and credentials.

## Hooks And Events

The module exposes no provider-specific hooks or events in version 1.0.0 / 100. Standard ProcessWire hooks around hookable WireMail methods remain subject to ProcessWire's normal hook behavior.

## Unsupported Or Ignored APIs

- `param()` values are ignored because they apply to PHP `mail()`, not SMTP.
- OAuth2 is not implemented.
- Google Workspace SMTP relay is not configured.
- Queues, retries, scheduling, templates, tracking, webhooks and bounce handling are not implemented.

## Internal APIs To Avoid

Do not call or extend `Smnv\WireMailGoogle\SmtpClient`, `MessageBuilder`, `Crypto`, `SettingsTrait`, `ConfigurationTrait` or `MailDeliveryTrait` from site code. Their signatures are internal and may change without deprecation. Do not call `hookModulesSaveConfig()` or manipulate `wiremail_google_settings` directly.

## Deprecations

There are no deprecated public APIs in the first release.