# MailCollector

> Captures every mail message dispatched during the request for the Mail panel.

[API reference](/docs/api/index.md) › [Debug](/docs/extensions/debug/reference/index.md) › [collectors](/docs/extensions/debug/reference/collectors/index.md) › MailCollector

| class | `yii\debug\collectors\MailCollector` |
| --- | --- |
| Extends | [`Collector`](/docs/extensions/debug/reference/collectors/collector/index.md) |
| Implements | [`CollectorInterface`](https://github.com/php-forge/debug/blob/e4fbb8c3238a4d011ceef5e0094344abd50deaf4/src/CollectorInterface.php) |
| Source | [`src/collectors/MailCollector.php`](https://github.com/yii2-extensions/debug/blob/main/src/collectors/MailCollector.php#L34) |

Captures every mail message dispatched during the request for the Mail panel.

## Properties

| Property | Type | Description | Defined by |
| --- | --- | --- | --- |
| <span id="property-mailPath"></span>`$mailPath` | `string` | Filesystem path (Yii alias) where every captured message is persisted as a `.eml` file. Default: `'@runtime/debug/mail'`. | `MailCollector` |
| <span id="property-module"></span>[`$module`](/docs/extensions/debug/reference/collectors/collector/index.md#property-module) | [`yii\debug\Module`](/docs/extensions/debug/reference/module/index.md)`\|null` | Debug module supplying the log target and sibling collectors, assigned by the module on registration. Default: `null`. | [`Collector`](/docs/extensions/debug/reference/collectors/collector/index.md) |

## Methods

| Method | Description | Defined by |
| --- | --- | --- |
| <span id="method-capture"></span>[`capture()`](/docs/extensions/debug/reference/collectors/collector/index.md#method-capture) final | Encodes the typed snapshot built by the subclass into the payload persisted for the panel. | [`Collector`](/docs/extensions/debug/reference/collectors/collector/index.md) |
| [`getMessagesFileName()`](#method-getMessagesFileName) | Returns the file names of the captured `.eml` files persisted under [`$mailPath`](/docs/extensions/debug/reference/collectors/mailcollector/index.md#property-mailPath). | `MailCollector` |
| [`id()`](#method-id) | Returns the stable ID pairing this collector with the Mail panel. | `MailCollector` |
| <span id="method-instrument"></span>[`instrument()`](/docs/extensions/debug/reference/collectors/collector/index.md#method-instrument) | Installs low-level instrumentation as soon as the module registers the collector, before the panels are built. | [`Collector`](/docs/extensions/debug/reference/collectors/collector/index.md) |
| [`reconcileFiles()`](#method-reconcileFiles) | Retries cleanup of aged `.eml` files no longer referenced by a retained snapshot. | `MailCollector` |
| [`removeFiles()`](#method-removeFiles) | Removes safe captured files associated with snapshots that were not committed or have been evicted. | `MailCollector` |
| <span id="method-shutdown"></span>[`shutdown()`](/docs/extensions/debug/reference/collectors/collector/index.md#method-shutdown) final | Deactivates the collector once, releasing any subscription created by [`start()`](/docs/extensions/debug/reference/collectors/collector/index.md#method-start). | [`Collector`](/docs/extensions/debug/reference/collectors/collector/index.md) |
| <span id="method-startup"></span>[`startup()`](/docs/extensions/debug/reference/collectors/collector/index.md#method-startup) final | Activates the collector once at the start of the request lifecycle. | [`Collector`](/docs/extensions/debug/reference/collectors/collector/index.md) |
| <span id="method-getLogMessages"></span>[`getLogMessages()`](/docs/extensions/debug/reference/collectors/collector/index.md#method-getLogMessages) protected | Returns the accumulated log messages, optionally filtered by level, category, and exclusion lists. | [`Collector`](/docs/extensions/debug/reference/collectors/collector/index.md) |
| <span id="method-getLogTarget"></span>[`getLogTarget()`](/docs/extensions/debug/reference/collectors/collector/index.md#method-getLogTarget) protected | Returns the initialized log target of the owning debug module. | [`Collector`](/docs/extensions/debug/reference/collectors/collector/index.md) |
| <span id="method-isStarted"></span>[`isStarted()`](/docs/extensions/debug/reference/collectors/collector/index.md#method-isStarted) protected | Returns whether the collector is active for the current request. | [`Collector`](/docs/extensions/debug/reference/collectors/collector/index.md) |
| [`snapshot()`](#method-snapshot) protected | Snapshots the captured messages, with their metadata (time, reply, bcc, cc, from, to, subject, headers, etc.). | `MailCollector` |
| [`start()`](#method-start) protected | Registers the mailer listener that persists each dispatched message and records its metadata. | `MailCollector` |
| [`stop()`](#method-stop) protected | Detaches the mailer listener and clears the captured messages, so a reused worker process starts clean. | `MailCollector` |

## Method details

### getMessagesFileName() <span id="method-getMessagesFileName"></span>

```php
public function getMessagesFileName(): array<int, string>
```

Returns the file names of the captured `.eml` files persisted under [`$mailPath`](/docs/extensions/debug/reference/collectors/mailcollector/index.md#property-mailPath).

**Returns**

`array<int, string>`: File names in send order.

### id() <span id="method-id"></span>

```php
public function id(): string
```

Returns the stable ID pairing this collector with the Mail panel.

**Returns**

`string`: Stable collector ID.

### reconcileFiles() <span id="method-reconcileFiles"></span>

```php
public function reconcileFiles(iterable<string> $referencedFiles): void
```

Retries cleanup of aged `.eml` files no longer referenced by a retained snapshot.

The grace period prevents a concurrent request's new mail from being deleted before its snapshot commits.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$referencedFiles` | `iterable<string>` | File names referenced by the current manifest. |

### removeFiles() <span id="method-removeFiles"></span>

```php
public function removeFiles(iterable<string> $files): void
```

Removes safe captured files associated with snapshots that were not committed or have been evicted.

**Parameters**

| Parameter | Type | Description |
| --- | --- | --- |
| `$files` | `iterable<string>` | Captured file names. |

### snapshot() <span id="method-snapshot"></span>

```php
protected function snapshot(): PHPForge\Debug\Panel\Mail\MailSnapshot|null
```

Snapshots the captured messages, with their metadata (time, reply, bcc, cc, from, to, subject, headers, etc.).

**Returns**

`PHPForge\Debug\Panel\Mail\MailSnapshot|null`: Captured mail payload; `null` when the collector never started.

### start() <span id="method-start"></span>

```php
protected function start(): void
```

Registers the mailer listener that persists each dispatched message and records its metadata.

### stop() <span id="method-stop"></span>

```php
protected function stop(): void
```

Detaches the mailer listener and clears the captured messages, so a reused worker process starts clean.