{"id":13395923,"url":"https://github.com/spatie/laravel-mail-preview","last_synced_at":"2025-04-27T03:56:27.683Z","repository":{"id":39637545,"uuid":"53718022","full_name":"spatie/laravel-mail-preview","owner":"spatie","description":"A mail driver to quickly preview mail","archived":false,"fork":false,"pushed_at":"2025-02-21T11:37:04.000Z","size":778,"stargazers_count":1219,"open_issues_count":0,"forks_count":80,"subscribers_count":22,"default_branch":"main","last_synced_at":"2025-04-24T08:57:48.653Z","etag":null,"topics":["laravel","mail","testing"],"latest_commit_sha":null,"homepage":"https://spatie.be/open-source","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/spatie.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"spatie","custom":"https://spatie.be/open-source/support-us"}},"created_at":"2016-03-12T06:54:41.000Z","updated_at":"2025-04-21T16:20:57.000Z","dependencies_parsed_at":"2024-01-15T04:07:00.248Z","dependency_job_id":"33dc0c92-9684-4dc8-823d-e3299f51ec2a","html_url":"https://github.com/spatie/laravel-mail-preview","commit_stats":{"total_commits":179,"total_committers":34,"mean_commits":5.264705882352941,"dds":0.558659217877095,"last_synced_commit":"42ae0568c7d6924e6d09823ebc3192d5bd588ee3"},"previous_names":["themsaid/laravel-mail-preview"],"tags_count":44,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spatie%2Flaravel-mail-preview","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spatie%2Flaravel-mail-preview/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spatie%2Flaravel-mail-preview/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spatie%2Flaravel-mail-preview/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/spatie","download_url":"https://codeload.github.com/spatie/laravel-mail-preview/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250597736,"owners_count":21456425,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["laravel","mail","testing"],"created_at":"2024-07-30T18:00:35.664Z","updated_at":"2025-04-24T08:57:55.643Z","avatar_url":"https://github.com/spatie.png","language":"PHP","funding_links":["https://github.com/sponsors/spatie","https://spatie.be/open-source/support-us"],"categories":["Popular Packages","Paquetes utiles"],"sub_categories":[],"readme":"\n# A mail driver to quickly preview mail\n\n[![Latest Version on Packagist](https://img.shields.io/packagist/v/spatie/laravel-mail-preview.svg?style=flat-square)](https://packagist.org/packages/spatie/laravel-mail-preview)\n[![run-tests](https://github.com/spatie/laravel-mail-preview/actions/workflows/run-tests.yml/badge.svg)](https://github.com/spatie/laravel-mail-preview/actions/workflows/run-tests.yml)\n[![Software License](https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square)](LICENSE.md)\n[![Total Downloads](https://img.shields.io/packagist/dt/spatie/laravel-mail-preview.svg?style=flat-square)](https://packagist.org/packages/spatie/laravel-mail-preview)\n\nThis package can display a small overlay whenever a mail is sent. The overlay contains a link to the mail that was just sent.\n\n\u003cimg alt=\"screenshot\" src=\"https://github.com/spatie/laravel-mail-preview/blob/main/docs/images/overlay.png?raw=true\" width=\"400\" /\u003e\n\nThis can be handy when testing out emails in a local environment. \n\n## Support us\n\n[\u003cimg src=\"https://github-ads.s3.eu-central-1.amazonaws.com/laravel-mail-preview.jpg?t=1\" width=\"419px\" /\u003e](https://spatie.be/github-ad-click/laravel-mail-preview)\n\nWe invest a lot of resources into creating [best in class open source packages](https://spatie.be/open-source). You can support us by [buying one of our paid products](https://spatie.be/open-source/support-us).\n\nWe highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on [our contact page](https://spatie.be/about-us). We publish all received postcards on [our virtual postcard wall](https://spatie.be/open-source/postcards).\n\n## Installation\n\nYou can install the package via composer:\n\n```bash\ncomposer require spatie/laravel-mail-preview\n```\n\n### Configuring the mail transport\n\nThis package contains a mail transport called `preview`. We recommend to only use this transport in non-production environments. To use the `preview` transport, change the `mailers.smtp.transport` to `preview` in your `config/mail.php` file:\n\n```php\n// in config/mail.php\n\n'mailers' =\u003e [\n    'smtp' =\u003e [\n        'transport' =\u003e 'preview',\n        // ...\n    ],\n    // ...\n],\n```\n\n### Registering the preview middleware route\n\nThe package can display a link to sent mails whenever they are sent. To use this feature, you must add the `Spatie\\MailPreview\\Http\\Middleware\\AddMailPreviewOverlayToResponse` middleware to the `web` middleware group in your kernel.\n\n```php\n// in app/Http/Kernel.php\n\nprotected $middlewareGroups = [\n    'web' =\u003e [\n        // other middleware\n        \n        \\Spatie\\MailPreview\\Http\\Middleware\\AddMailPreviewOverlayToResponse::class,\n    ],\n    \n    // ...\n];\n```\n\nYou must also add the `mailPreview` to your routes file. Typically, the routes file will be located at `routes/web.php`.\n\n```php\n// in routes/web.php\n\nRoute::mailPreview();\n```\n\nThis will register a route to display sent mails at `/spatie-mail-preview`. To customize the URL, pass the URL you want to the macro.\n\n```php\nRoute::mailPreview('custom-url-where-sent-mails-will-be-shown');\n```\n\n### Publishing the config file\n\nOptionally, you can publish the config file with:\n\n```bash\nphp artisan vendor:publish --provider=\"Spatie\\MailPreview\\MailPreviewServiceProvider\" --tag=\"mail-preview-config\"\n```\n\nThis is the content of the config file that will be published at `config/mail-preview.php`:\n\n```php\nreturn [\n    /*\n     * By default, the overlay will only be shown and mail will only be stored\n     * when the application is in debug mode.\n     */\n    'enabled' =\u003e env('APP_DEBUG', false),\n\n    /*\n     * All mails will be stored in the given directory.\n     */\n    'storage_path' =\u003e storage_path('email-previews'),\n\n    /*\n     * This option determines how long generated preview files will be kept.\n     */\n    'maximum_lifetime_in_seconds' =\u003e 60,\n\n    /*\n     * When enabled, a link to mail will be added to the response\n     * every time a mail is sent.\n     */\n    'show_link_to_preview' =\u003e true,\n\n    /*\n     * Determines how long the preview pop up should remain visible.\n     *\n     * Set this to `false` if the popup should stay visible.\n     */\n    'popup_timeout_in_seconds' =\u003e 8,\n    \n    /**\n     * Determines the date format used for the file names.\n     *\n     * The default 'u' stands for microseconds.\n     */\n    'filename_date_format' =\u003e 'u',\n];\n\n```\n\n### Publishing the views\n\nOptionally, you can publish the views that render the preview overlay and the mail itself.\n\n```bash\nphp artisan vendor:publish --provider=\"Spatie\\MailPreview\\MailPreviewServiceProvider\" --tag=\"mail-preview-views\"\n```\n\nYou can modify the views that will be published at `resources/views/vendor/mail-preview` to your liking.\n\n## Usage\n\nEverytime an email is sent, an `.html` and `.eml` file will be saved in the directory specified in the `storage_path` of the `mail-preview` config file.  The name includes the first recipient and the subject:\n\n```\n1457904864_john_at_example_com_invoice_000234.html\n1457904864_john_at_example_com_invoice_000234.eml\n```\n\nYou can open the `.html` file in a web browser.  The `.eml` file in your default email client to have a realistic look\nof the final output.\n\n### Preview in a web browser\n\nWhen you open the `.html` file in a web browser you'll be able to see how your email will look.\n\nAt the beginning of the generated file you'll find an HTML comment with all the message info:\n\n```html\n\u003c!--\nFrom:{\"info@acme.com\":\"Acme HQ\"},\nto:{\"jack@gmail.com\":\"Jack Black\"},\nreply-to:{\"info@acme.com\"},\ncc:[{\"finance@acme.com\":\"Acme Finance\"}, {\"management@acme.com\":\"Acme Management\"}],\nbcc:null,\nsubject:Invoice #000234\n--\u003e\n```\n\n### Events\n\nWhenever a mail is stored on disk, the `Spatie\\MailPreview\\Events\\MailStoredEvent` will be fired. It has three public properties:\n\n- `message`: an instance of `Swift_Mime_SimpleMessage`\n- `pathToHtmlVersion`: the path to the html version of the sent mail\n- `pathToEmlVersion`: the path to the email version of the sent mail\n\n### Making assertions against sent mails\n\nCurrently, using Laravel's `Mail::fake` you cannot make any assertions against the content of a mail, as the using the fake will not render the mail. \n\nThe `SentMails` facade provided this package does allow you to make asserts against the content.\n\nThis allows you to make assertions on the content of a mail, without having the mailable in scope.\n\n```php\n// in a test\n\nArtisan::call(CommandThatSendsMail::class);\n\nSpatie\\MailPreview\\Facades\\SentMails::assertLastContains('something in your mail');\n```\n\nLet's explain other available assertions method using this mailable as example.\n\n```php\nnamespace App\\Mail;\n\nuse Illuminate\\Mail\\Mailable;\n\nclass MyNewSongMailable extends Mailable\n{\n    public function build()\n    {\n        $this\n            -\u003eto('ringo@example.com')\n            -\u003ecc('paul@examle.com')\n            -\u003ebcc('john@examle.com')\n            -\u003esubject('Here comes the sun')\n            -\u003ehtml(\"It's been a long cold lonely winter\");\n    }\n}\n```\n\nIn your code you can send that mailable with:\n\n```php\nMail::send(new MyNewSongMailable());\n```\n\nIn your tests you can assert that the mail was sent using the `assertSent` function. You should pass a callable to `assertSent` which will get an instance of `SentMail` to it. Each sent mail will be passed to the callable. If the callable returns `true` the assertions passes.\n\n```php\nuse Spatie\\MailPreview\\Facades\\SentMails;\nuse \\Spatie\\MailPreview\\SentMails\\SentMail;\n\nSentMails::assertSent(fn (SentMail $mail) =\u003e $mail-\u003ebodyContains('winter')); // will pass\nSentMails::assertSent(fn (SentMail $mail) =\u003e $mail-\u003ebodyContains('spring')); // will not pass\n```\n\nYou can use as many assertion methods on the `SentMail` as you like.\n\n```php\nSentMails::assertSent(function (SentMail $mail)  {\n    return\n        $mail-\u003esubjectContains('sun') \u0026\u0026\n        $mail-\u003ehasTo('ringo@example.com')\n        $mail-\u003ebodyContains('winter');\n```\n\nThe `Spatie\\MailPreview\\Facades\\SentMails` has the following assertions methods:\n\n- `assertCount(int $expectedCount)`: assert how many mails were sent\n- `assertLastContains(string $expectedSubstring)`: assert that the body of the last sent mail contains a given substring\n- `assertSent($findMailCallable, int $expectedCount = 1)`: explained above\n- `assertTimesSent(int $expectedCount, Closure $findMail)`\n- `assertNotSent(Closure $findMail)`\n\nAdditionally, the `Spatie\\MailPreview\\Facades\\SentMails` has these methods:\n\n- `all`: returns an array of sent mails. Each item will be an instance of  `sentMail`\n- `count()`: returns the amount of mails sent\n- `last`: returns an instance of `SentMail` for the last sent mail. If no mail was sent `null` will be returned.\n- `lastContains`: returns `true` if the body of the last sent mail contains the given substring\n- `timesSent($findMailCallable)`: returns the amount of mails the were sent and that passed the given callable\n\nThe `sentMail` class provides these assertions:\n\n- `assertSubjectContains($expectedSubstring)`\n- `assertFrom($expectedAddress)`\n- `assertTo$expectedAddress)`\n- `assertCc($expectedAddress)`\n- `assertBcc($expectedAddress)`\n- `assertContains($substring)`: will pass if the body of the mail contains the substring\n\nAdditionally, `sentMail` contains these methods:\n\n- `subject()`: return the body of a mail\n- `to()`: returns all to recipients as an array\n- `cc()`: returns all cc recipients as an array\n- `bcc()`: returns all bcc recipients as an array\n- `body()`: returns the body of a mail\n- `subjectContains)`: returns a boolean\n- `hasFrom($expectedAddress)`: return a boolean\n- `hasTo($expectedAddress)`: return a boolean\n- `hasCc($expectedAddress)`: return a boolean\n- `hasBcc($expectedAddress)`: return a boolean\n\n## Changelog\n\nPlease see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.\n\n## UPGRADING\n\nPlease see [UPGRADING](UPGRADING.md) for what to do to switch over from `themsaid/laravel-mail-preview`, and how to upgrade to newer major versions.\n\n## Contributing\n\nPlease see [CONTRIBUTING](https://github.com/spatie/.github/blob/main/CONTRIBUTING.md) for details.\n\n## Security Vulnerabilities\n\nPlease review [our security policy](../../security/policy) on how to report security vulnerabilities.\n\n## Credits\n\n- [Freek Van der Herten](https://github.com/freekmurze)\n- [Mohamed Said](https://github.com/themsaid)\n- [All Contributors](../../contributors)\n\nThe initial version of this package was created by Mohamed Said, who graciously entrusted this package to us at Spatie.\n\n## License\n\nThe MIT License (MIT). Please see [License File](LICENSE.md) for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspatie%2Flaravel-mail-preview","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspatie%2Flaravel-mail-preview","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspatie%2Flaravel-mail-preview/lists"}