# redberryproducts/mailbox-for-laravel architecture

> Architecture diagram of the GitHub repository redberryproducts/mailbox-for-laravel, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/redberryproducts/mailbox-for-laravel
- Repository: https://github.com/redberryproducts/mailbox-for-laravel

## Overview

Mailbox for Laravel intercepts outgoing Laravel mail, normalizes and captures rendered messages and attachments, then exposes them through a local dashboard and a fluent assertion API. Its main runtime path is documented as transport → normalizer → capture service → stores. The graph also preserves dashboard management, search, attachment handling, optional real delivery, and testing capabilities. Some frontend and controller internals were not sampled; edges involving those areas rely on README documentation or route registrations rather than assumed component-level calls.

Main entry points: [`src/CaptureService.php`](https://github.com/redberryproducts/mailbox-for-laravel/blob/main/src/CaptureService.php) (Capture service), [`routes/mailbox.php`](https://github.com/redberryproducts/mailbox-for-laravel/blob/main/routes/mailbox.php) (Mailbox routes), [`src/Http/Controllers/MailboxController.php`](https://github.com/redberryproducts/mailbox-for-laravel/blob/main/src/Http/Controllers/MailboxController.php) (Mailbox listing), [`src/Contracts/AttachmentStore.php`](https://github.com/redberryproducts/mailbox-for-laravel/blob/main/src/Contracts/AttachmentStore.php) (Attachment stores)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Mail capture"]
  node_transport["Mailbox transport"]
  node_normalizer["Message normalizer"]
  node_capture_service["Capture service<br/>[CaptureService.php]"]
  node_message_data["Message DTO"]
end

subgraph group_persistence["Persistence and search"]
  node_store_manager["Store manager<br/>[StoreManager.php]"]
  node_message_store["Message store<br/>[MessageStore.php]"]
  node_database_store[("Database store")]
  node_file_store["File store<br/>[FileStorage.php]"]
  node_attachment_store["Attachment stores"]
  node_database_attachments[("Database attachments")]
  node_file_attachments["File attachments"]
  node_search["Message search"]
end

subgraph group_dashboard["Mailbox dashboard"]
  node_routes["Mailbox routes<br/>[mailbox.php]"]
  node_authorization["Mailbox authorization"]
  node_mailbox_controller["Mailbox listing"]
  node_message_actions["Message actions<br/>[SeenController.php]"]
  node_delete_clear["Delete and clear"]
  node_attachment_controller["Attachment delivery"]
  node_cid_rewriter["Inline image rewriting<br/>[CidRewriter.php]"]
  node_dashboard_ui["Mailbox dashboard UI<br/>[MailboxLayout.vue]"]
  node_polling["Live polling"]
  node_test_mail["Test email endpoint"]
end

subgraph group_testing["Email testing"]
  node_facade["Mailbox facade<br/>[Mailbox.php]"]
  node_assertions["Collection assertions"]
  node_message_assertion["Message assertions"]
end

node_app(("Laravel application"))
node_dashboard_user(("Dashboard user"))
node_decorated_mailer["Configured mailer"]

node_app -->|"sends mail through"| node_transport
node_transport -->|"normalizes message"| node_normalizer
node_transport -->|"captures message"| node_capture_service
node_transport -.->|"forwards optionally"| node_decorated_mailer
node_capture_service -->|"persists message"| node_message_store
node_capture_service -->|"persists attachments"| node_attachment_store
node_capture_service -->|"creates DTOs"| node_message_data
node_store_manager -->|"resolves driver"| node_database_store
node_store_manager -->|"resolves driver"| node_file_store
node_database_store -->|"applies search"| node_search
node_file_store -->|"filters messages"| node_search
node_database_attachments -->|"implements contract"| node_attachment_store
node_file_attachments -.->|"implements contract"| node_attachment_store
node_dashboard_user -->|"opens dashboard"| node_routes
node_routes -->|"guards access"| node_authorization
node_routes -->|"routes listing"| node_mailbox_controller
node_routes -->|"routes seen action"| node_message_actions
node_routes -->|"routes management"| node_delete_clear
node_routes -->|"routes downloads"| node_attachment_controller
node_routes -->|"routes test send"| node_test_mail
node_mailbox_controller -->|"lists messages"| node_capture_service
node_mailbox_controller -->|"rewrites inline images"| node_cid_rewriter
node_mailbox_controller -->|"loads attachment metadata"| node_attachment_store
node_message_actions -->|"updates read state"| node_capture_service
node_delete_clear -->|"deletes messages"| node_capture_service
node_attachment_controller -->|"reads attachment"| node_attachment_store
node_mailbox_controller -->|"serves dashboard data"| node_dashboard_ui
node_dashboard_ui -.->|"refreshes list"| node_polling
node_test_mail -->|"sends test message"| node_capture_service
node_facade -->|"exposes mailbox API"| node_capture_service
node_facade -->|"dispatches assertions"| node_assertions
node_assertions -.->|"builds message checks"| node_message_assertion

click node_transport "https://github.com/redberryproducts/mailbox-for-laravel/blob/main/src/Transport/MailboxTransport.php"
click node_normalizer "https://github.com/redberryproducts/mailbox-for-laravel/blob/main/src/Support/MessageNormalizer.php"
click node_capture_service "https://github.com/redberryproducts/mailbox-for-laravel/blob/main/src/CaptureService.php"
click node_message_data "https://github.com/redberryproducts/mailbox-for-laravel/blob/main/src/DTO/MailboxMessageData.php"
click node_store_manager "https://github.com/redberryproducts/mailbox-for-laravel/blob/main/src/StoreManager.php"
click node_message_store "https://github.com/redberryproducts/mailbox-for-laravel/blob/main/src/Contracts/MessageStore.php"
click node_database_store "https://github.com/redberryproducts/mailbox-for-laravel/blob/main/src/Storage/DatabaseMessageStore.php"
click node_file_store "https://github.com/redberryproducts/mailbox-for-laravel/blob/main/src/Storage/FileStorage.php"
click node_attachment_store "https://github.com/redberryproducts/mailbox-for-laravel/blob/main/src/Contracts/AttachmentStore.php"
click node_database_attachments "https://github.com/redberryproducts/mailbox-for-laravel/blob/main/src/Storage/DatabaseAttachmentStore.php"
click node_file_attachments "https://github.com/redberryproducts/mailbox-for-laravel/blob/main/src/Storage/FileAttachmentStore.php"
click node_search "https://github.com/redberryproducts/mailbox-for-laravel/blob/main/src/Search/DefaultMessageSearch.php"
click node_routes "https://github.com/redberryproducts/mailbox-for-laravel/blob/main/routes/mailbox.php"
click node_authorization "https://github.com/redberryproducts/mailbox-for-laravel/blob/main/src/Http/Middleware/AuthorizeMailboxMiddleware.php"
click node_mailbox_controller "https://github.com/redberryproducts/mailbox-for-laravel/blob/main/src/Http/Controllers/MailboxController.php"
click node_message_actions "https://github.com/redberryproducts/mailbox-for-laravel/blob/main/src/Http/Controllers/SeenController.php"
click node_delete_clear "https://github.com/redberryproducts/mailbox-for-laravel/blob/main/src/Http/Controllers/DeleteMailboxMessageController.php"
click node_attachment_controller "https://github.com/redberryproducts/mailbox-for-laravel/blob/main/src/Http/Controllers/AttachmentController.php"
click node_cid_rewriter "https://github.com/redberryproducts/mailbox-for-laravel/blob/main/src/Support/CidRewriter.php"
click node_dashboard_ui "https://github.com/redberryproducts/mailbox-for-laravel/blob/main/resources/js/components/mail/MailboxLayout.vue"
click node_polling "https://github.com/redberryproducts/mailbox-for-laravel/blob/main/resources/js/composables/useMailboxPolling.ts"
click node_test_mail "https://github.com/redberryproducts/mailbox-for-laravel/blob/main/src/Http/Controllers/SendTestMailController.php"
click node_facade "https://github.com/redberryproducts/mailbox-for-laravel/blob/main/src/Facades/Mailbox.php"
click node_assertions "https://github.com/redberryproducts/mailbox-for-laravel/blob/main/src/Testing/MailboxAssertions.php"
click node_message_assertion "https://github.com/redberryproducts/mailbox-for-laravel/blob/main/src/Testing/PendingMailboxMessageAssertion.php"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_transport,node_normalizer,node_capture_service,node_message_data,node_dashboard_user toneBlue
class node_store_manager,node_message_store,node_database_store,node_file_store,node_attachment_store,node_database_attachments,node_file_attachments,node_search toneAmber
class node_routes,node_authorization,node_mailbox_controller,node_message_actions,node_delete_clear,node_attachment_controller,node_cid_rewriter,node_dashboard_ui,node_polling,node_test_mail toneMint
class node_facade,node_assertions,node_message_assertion toneRose
class node_app,node_decorated_mailer toneIndigo
```

## Components

### Mail capture

- [Mailbox transport](https://github.com/redberryproducts/mailbox-for-laravel/blob/main/src/Transport/MailboxTransport.php): `src/Transport/MailboxTransport.php`
- [Message normalizer](https://github.com/redberryproducts/mailbox-for-laravel/blob/main/src/Support/MessageNormalizer.php): `src/Support/MessageNormalizer.php`
- [Capture service](https://github.com/redberryproducts/mailbox-for-laravel/blob/main/src/CaptureService.php): `src/CaptureService.php`
- [Message DTO](https://github.com/redberryproducts/mailbox-for-laravel/blob/main/src/DTO/MailboxMessageData.php): `src/DTO/MailboxMessageData.php`

### Persistence and search

- [Store manager](https://github.com/redberryproducts/mailbox-for-laravel/blob/main/src/StoreManager.php): `src/StoreManager.php`
- [Message store](https://github.com/redberryproducts/mailbox-for-laravel/blob/main/src/Contracts/MessageStore.php): `src/Contracts/MessageStore.php`
- [Database store](https://github.com/redberryproducts/mailbox-for-laravel/blob/main/src/Storage/DatabaseMessageStore.php): `src/Storage/DatabaseMessageStore.php`
- [File store](https://github.com/redberryproducts/mailbox-for-laravel/blob/main/src/Storage/FileStorage.php): `src/Storage/FileStorage.php`
- [Attachment stores](https://github.com/redberryproducts/mailbox-for-laravel/blob/main/src/Contracts/AttachmentStore.php): `src/Contracts/AttachmentStore.php`
- [Database attachments](https://github.com/redberryproducts/mailbox-for-laravel/blob/main/src/Storage/DatabaseAttachmentStore.php): `src/Storage/DatabaseAttachmentStore.php`
- [File attachments](https://github.com/redberryproducts/mailbox-for-laravel/blob/main/src/Storage/FileAttachmentStore.php): `src/Storage/FileAttachmentStore.php`
- [Message search](https://github.com/redberryproducts/mailbox-for-laravel/blob/main/src/Search/DefaultMessageSearch.php): `src/Search/DefaultMessageSearch.php`

### Mailbox dashboard

- [Mailbox routes](https://github.com/redberryproducts/mailbox-for-laravel/blob/main/routes/mailbox.php): `routes/mailbox.php`
- [Mailbox authorization](https://github.com/redberryproducts/mailbox-for-laravel/blob/main/src/Http/Middleware/AuthorizeMailboxMiddleware.php): `src/Http/Middleware/AuthorizeMailboxMiddleware.php`
- [Mailbox listing](https://github.com/redberryproducts/mailbox-for-laravel/blob/main/src/Http/Controllers/MailboxController.php): `src/Http/Controllers/MailboxController.php`
- [Message actions](https://github.com/redberryproducts/mailbox-for-laravel/blob/main/src/Http/Controllers/SeenController.php): `src/Http/Controllers/SeenController.php`
- [Delete and clear](https://github.com/redberryproducts/mailbox-for-laravel/blob/main/src/Http/Controllers/DeleteMailboxMessageController.php): `src/Http/Controllers/DeleteMailboxMessageController.php`
- [Attachment delivery](https://github.com/redberryproducts/mailbox-for-laravel/blob/main/src/Http/Controllers/AttachmentController.php): `src/Http/Controllers/AttachmentController.php`
- [Inline image rewriting](https://github.com/redberryproducts/mailbox-for-laravel/blob/main/src/Support/CidRewriter.php): `src/Support/CidRewriter.php`
- [Mailbox dashboard UI](https://github.com/redberryproducts/mailbox-for-laravel/blob/main/resources/js/components/mail/MailboxLayout.vue): `resources/js/components/mail/MailboxLayout.vue`
- [Live polling](https://github.com/redberryproducts/mailbox-for-laravel/blob/main/resources/js/composables/useMailboxPolling.ts): `resources/js/composables/useMailboxPolling.ts`
- [Test email endpoint](https://github.com/redberryproducts/mailbox-for-laravel/blob/main/src/Http/Controllers/SendTestMailController.php): `src/Http/Controllers/SendTestMailController.php`

### Email testing

- [Mailbox facade](https://github.com/redberryproducts/mailbox-for-laravel/blob/main/src/Facades/Mailbox.php): `src/Facades/Mailbox.php`
- [Collection assertions](https://github.com/redberryproducts/mailbox-for-laravel/blob/main/src/Testing/MailboxAssertions.php): `src/Testing/MailboxAssertions.php`
- [Message assertions](https://github.com/redberryproducts/mailbox-for-laravel/blob/main/src/Testing/PendingMailboxMessageAssertion.php): `src/Testing/PendingMailboxMessageAssertion.php`

### Other components

- **Laravel application**
- **Dashboard user**
- **Configured mailer**

## Connections

- Laravel application → Mailbox transport: sends mail through (evidence: `README.md`)
- Mailbox transport → Message normalizer: normalizes message (evidence: `src/Transport/MailboxTransport.php`)
- Mailbox transport → Capture service: captures message (evidence: `src/Transport/MailboxTransport.php`)
- Mailbox transport → Configured mailer: forwards optionally (evidence: `README.md`)
- Capture service → Message store: persists message (evidence: `src/CaptureService.php`)
- Capture service → Attachment stores: persists attachments (evidence: `README.md`)
- Capture service → Message DTO: creates DTOs (evidence: `src/CaptureService.php`)
- Store manager → Database store: resolves driver (evidence: `src/StoreManager.php`)
- Store manager → File store: resolves driver (evidence: `src/StoreManager.php`)
- Database store → Message search: applies search (evidence: `src/Storage/DatabaseMessageStore.php`)
- File store → Message search: filters messages (evidence: `src/Storage/FileStorage.php`)
- Database attachments → Attachment stores: implements contract (evidence: `src/Storage/DatabaseAttachmentStore.php`)
- File attachments → Attachment stores: implements contract
- Dashboard user → Mailbox routes: opens dashboard (evidence: `README.md`)
- Mailbox routes → Mailbox authorization: guards access (evidence: `routes/mailbox.php`)
- Mailbox routes → Mailbox listing: routes listing (evidence: `routes/mailbox.php`)
- Mailbox routes → Message actions: routes seen action (evidence: `routes/mailbox.php`)
- Mailbox routes → Delete and clear: routes management (evidence: `routes/mailbox.php`)
- Mailbox routes → Attachment delivery: routes downloads (evidence: `routes/mailbox.php`)
- Mailbox routes → Test email endpoint: routes test send (evidence: `routes/mailbox.php`)
- Mailbox listing → Capture service: lists messages (evidence: `src/Http/Controllers/MailboxController.php`)
- Mailbox listing → Inline image rewriting: rewrites inline images (evidence: `src/Http/Controllers/MailboxController.php`)
- Mailbox listing → Attachment stores: loads attachment metadata (evidence: `src/Http/Controllers/MailboxController.php`)
- Message actions → Capture service: updates read state (evidence: `src/Http/Controllers/SeenController.php`)
- Delete and clear → Capture service: deletes messages (evidence: `src/Http/Controllers/DeleteMailboxMessageController.php`)
- Attachment delivery → Attachment stores: reads attachment (evidence: `src/Http/Controllers/AttachmentController.php`)
- Mailbox listing → Mailbox dashboard UI: serves dashboard data (evidence: `README.md`)
- Mailbox dashboard UI → Live polling: refreshes list
- Test email endpoint → Capture service: sends test message (evidence: `src/Http/Controllers/SendTestMailController.php`)
- Mailbox facade → Capture service: exposes mailbox API (evidence: `src/Facades/Mailbox.php`)
- Mailbox facade → Collection assertions: dispatches assertions (evidence: `src/Facades/Mailbox.php`)
- Collection assertions → Message assertions: builds message checks
