PHPackages 2am.tech/laravel-mail-api - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Framework](/categories/framework) 4. / 5. 2am.tech/laravel-mail-api ActiveProject[Framework](/categories/framework) 2am.tech/laravel-mail-api ========================= Laravel mail API microservice 1.0.1(2y ago)7253[1 PRs](https://github.com/2amigos/laravel-mail-api/pulls)MITPHPPHP ^8.1 Since Aug 15Pushed 2y ago10 watchersCompare [ Source](https://github.com/2amigos/laravel-mail-api)[ Packagist](https://packagist.org/packages/2am.tech/laravel-mail-api)[ Docs](https://github.com/2amigos/laravel-mail-api)[ RSS](/packages/2amtech-laravel-mail-api/feed)WikiDiscussions main Synced today READMEChangelog (3)Dependencies (14)Versions (7)Used By (0) Laravel Mail API ================ [](#laravel-mail-api) [ ![Laravel Mail API](./assets/img/mail-api-service.png) ](https://2am.tech/our-work/open-source) [![Build](https://github.com/2amigos/laravel-mail-api/actions/workflows/ci.yml/badge.svg)](https://github.com/2amigos/laravel-mail-api/actions/workflows/ci.yml)[![Software License](https://camo.githubusercontent.com/b60331a2084501dc07cf6d6964c0da58dd005d89c45cf3b28b4b22b60f5ec00f/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4253442d627269676874677265656e2e7376673f7374796c653d666c61742d737175617265)](LICENSE.md)[![Codacy Badge Quality](https://camo.githubusercontent.com/7f189dc93511d0588fac0490d6c01113c88d0508f08a6e0b407bad4da18496a3/68747470733a2f2f6170702e636f646163792e636f6d2f70726f6a6563742f62616467652f47726164652f3061376239306362373530353431313362333937373138366565383963633333)](https://app.codacy.com?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)[![Codacy Badge Coverage](https://camo.githubusercontent.com/2f1afb4528f813141193940a7e643c7c2741c58dc9d674bf0061e733efa9b3df/68747470733a2f2f6170702e636f646163792e636f6d2f70726f6a6563742f62616467652f436f7665726167652f3061376239306362373530353431313362333937373138366565383963633333)](https://app.codacy.com?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_coverage) About Mail API Service ---------------------- [](#about-mail-api-service) Laravel Mail API is an email microservice to avoid having to configure mail over and over on projects involving microservices infrastructure. It uses Signed AppKeys to handle the authentications through requests. The mailer transport interface was build using [Laravel Mail](https://laravel.com/docs/10.x/mail) (powered by [Symfony Mailer](https://symfony.com/doc/6.2/mailer.html)) with [Markdown Mail Notifications](https://laravel.com/docs/10.x/notifications#markdown-mail-notifications) to enhance the email layout configuration. To accomplish dispatching emails with an efficient response time, Laravel Mail API uses [Laravel Queues](https://laravel.com/docs/10.x/queues)to execute the tasks in background. We already have configured a driver for **Redis** ([Predis](https://github.com/predis/predis)) connection. You are free to configure other driver if it's needed. Finally, it makes use of [Laravel Localization](https://laravel.com/docs/10.x/localization#main-content) for content internationalization and [Laravel Logs](https://laravel.com/docs/10.x/logging#main-content)for logging. Install ------- [](#install) ``` $ composer create-project 2am.tech/laravel-mail-api app ``` Configuration ------------- [](#configuration) ### Docker Container Configuration [](#docker-container-configuration) A docker image was provided through [Laravel Sail](https://laravel.com/docs/10.x/sail#main-content). You can configure a [shell alias for Sail](https://laravel.com/docs/10.x/sail#configuring-a-shell-alias) command and make it easier to access. Please, refer to Sail Docs to know more about [executing commands in your application's container](https://laravel.com/docs/10.x/sail#executing-sail-commands). To start up/stop the docker container, use the following commands: To be able to use the docker container, you need to first install the dependencies. To achieve that, you must execute the given command: ``` $ docker run --rm \ -u "$(id -u):$(id -g)" \ -v "$(pwd):/var/www/html" \ -w /var/www/html \ laravelsail/php82-composer:latest \ composer install --ignore-platform-reqs ``` ``` // to start up the container $ ./vendor/bin/sail up -d # to stop the container $ ./vendor/bin/sail stop ``` If you're using Laravel Sail, refer to **.env.sail** for redis connection strings. The **.env.example** file gives the basic structure your project must have in order to run the service properly. Copy its content to **.env** file. ### Application Configuration [](#application-configuration) As mentioned before, we're using Signed AppKeys for requests authentication. First, you have to define you're Access Token (AppKey and AppSecret) on `./config/laravel-mail-api`, on `AccessTokens` section. We already provided a sample access key. ``` # register access token ... 'accessTokens' => [ 'access-key-user-1' => [ 'appKey' => 'jwYitJJOop2v', 'appSecret' => 'token', ], ... ]; ``` You can register as many access token it's necessary for your microservices. With the access token defined, we just need to sign it to and add its values to the request header. ### Access Token Sign Algorithm [](#access-token-sign-algorithm) Define a hash algorithm to create a hashed token. The default is `sha512`. You can define it on by adding `HASH_SIGNATURE` on the `.env` file: `HASH_SIGNATURE=sha512` To create a signature for you access token, you follow this steps: Get the current timestamp (on UTC) on ISO-8601 format. ``` $ date -u +'%Y-%m-%dT%H:%M:%S.%3NZ' # ouputs date format $ 2023-08-10T04:32:25.620Z ``` Then, simple hash your AppKey with the gotten timestamp, using your AppSecret as the hash password. ``` signature: HASH-HMACK( AppKey + timestamp, AppSecret ) # with our sample values signature: HASH-HMACK( 'jwYitJJOop2v' + '2023-08-10T04:32:25.620Z', 'token' ) # output cb64bbccdff25dcaba24e4c029aa54d99522a3e2e70e5be7be1b48dd8816b4e05b0102f2a2775c895ac73f649b45f6f97f755a112a9f4a206e4053128fc5ada9 ``` A command was created to help the signature creation, for testing purposes: ``` $ php artisan app:create-signature ``` ### Email Transport Configuration [](#email-transport-configuration) You must configure your mailer transport on .env file as well. This project was built using SMTP. Laravel Mail provides an easy way to [configure](https://laravel.com/docs/10.x/mail#configuration)the driver your project needs. This is a sample SMTP Driver configuration: ``` MAIL_MAILER=smtp MAIL_HOST={smtp-server} MAIL_PORT={smtp-port} MAIL_USERNAME={smtp-mailer-email-address} MAIL_PASSWORD={smtp-mailer-email-password{ MAIL_ENCRYPTION=tls ``` Usage ----- [](#usage) To serve the application, Laravel provides the handy built in command **serve** ``` $ php artisan serve # or on Sail $ ./vendor/bin/sail php artisan serve ``` This command serve your application at . If you run the command through Laravel Sail, the application will be served on port 80 instead . Endpoints --------- [](#endpoints) The API has one endpoint: `/api/email/send`. A postman collection `Laravel Mail API` has been served to simplify the testing process. ### /api/email/send [](#apiemailsend) In order to have the authentication mechanism working, we must add the following headers: ``` Authentication: Bearear {signature} ts: {timestap (used to sign the appKey)} accessToken: {your access token} # using our sample values Authentication: Bearear cb64bbccdff25dcaba24e4c029aa54d99522a3e2e70e5be7be1b48dd8816b4e05b0102f2a2775c895ac73f649b45f6f97f755a112a9f4a206e4053128fc5ada9 ts: 2023-08-10T04:32:25.620Z accessToken: access-key-user-1 ``` Then you can send `multipart/form-data` request with the following parameters: - from - sender *(optional)* - to - receiver *(optional)* - subject - language *(optional, default=en)* - template *(optional, default defined on the application)* - attachments\[\] *(optional)* Here is a sample request: ``` curl --location 'http://localhost:8000/api/email/send' \ --header 'accessKey: tests' \ --header 'ts: 2023-08-10T04:56:50+00:00' \ --header 'Authorization: Bearer a7ef7032999db841c75a7a2de4d40106e6de19b7c269b722f81bc51a1f713f6642d25e3bc25af7b04f9a385ef8f9c9ed346e029d0262cbc61dde2f640d0f8c48' \ --form 'from="test@mail.com"' \ --form 'to="receiver@email.com"' \ --form 'sender="2am.tech"' \ --form 'receiver="Amigo OSS"' \ --form 'subject="test api"' ``` Done. Now your new message is on the queue, ready to be dispatched. To achieve that, you just need to run this command: ``` $ php artisan queue:work # or on sail $ ./vendor/bin/sail php artisan queue:work ``` #### Email Attachments [](#email-attachments) The `/api/email/send` endpoint apply validations for attachments mimetypes. By default, the application will allow `PDF` and any `Image` mimetypes. You can easily set an array of your needed mimetypes, or even set a string `'*'` to allow any mimetype. e.g. to allow any file mimetype, you just need to change this line on `config/laravel-mail-api.php`: ``` use Laravel\Sanctum\PersonalAccessToken; // from this return [ ... 'attachmentsAllowedMimetypes' => env('ATTACHMENT_MIMETYPES', ['application/pdf', 'image/*']), ]; // to this return [ ... 'attachmentsAllowedMimetypes' => env('ATTACHMENT_MIMETYPES', '*'), ]; ``` ### Customization [](#customization) As mentioned before, this service uses [Markdown Mail Notifications](https://laravel.com/docs/10.x/notifications#markdown-mail-notifications) to enhance the email layout configuration. You can find the template files for Markdown published at `resources/views/vendor/mail/html`. The email body is set on template files. It already has [Laravel Localization](https://laravel.com/docs/10.x/localization#main-content) to provide an internationalization feature to it. You can check the default template at `recources/views/templates/hello-world.blade.php` and the password template at `resruoces\views\templates\password.blade.php` for reference, as they've been written with localization already. You can define for how long a token will be valid by declaring the constant `TOKEN_TIME` (in minutes) in your .env file. Default is 60. You can define the default email template declaring `DEFAULT_TEMPLATE`, where the default is `hello-world` and the default language by declaring the `LANGUAGE` constant (default `en`). ### Deploying [](#deploying) Although the queue work command is handy and makes it really easy to consume the queue while testing the application, but it's extremely recommended to use [Supervisor](http://supervisord.org/) when deploying to production. Laravel has a nice guide to properly [configure](https://laravel.com/docs/10.x/queues#supervisor-configuration) the Supervisor. Serverless deployment to AWS Lambda ----------------------------------- [](#serverless-deployment-to-aws-lambda) This project uses [Bref](https://bref.sh/) framework to empower a smoothly deployment to AWS Lambda. It has a tiny list of dependencies to achieve that: - Node.js 14.0+ - [Serverless](https://www.serverless.com/framework/docs) framework - and, an AWS account (key and secret). To install the Serverless framework: ``` $ npm install -g serverless ``` Install Serverless plugin dependency: ``` $ npm install ``` And them, setup the AWS credentials for the Serverless framework: ``` $ serverless config credentials --provider aws --key "key" --secret "secret" ``` You can change the project name on file `serverless.yml` to match your project name, right on the first line: ``` service: laravel-mail-api ``` Last step before the actual deployment is to clear local cashed files: ``` $ php artisan config:clear ``` and, them: ``` $ serverless deploy ``` Once the process is finished, you will be prompted with the endpoint, functions and jobs created on AWS Lambda! Contributing ------------ [](#contributing) Please, see [CONTRIBUTING](./contributing.md) for details. License ------- [](#license) The BSD License (BSD). Please see [License File](./license.md) for more information/ > [![2am.tech](https://avatars.githubusercontent.com/u/3440791?s=200&v=4)](https://2am.tech/) Web development has never been so fun! ### Health Score 28 — LowBetter than 52% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity14 Limited adoption so far Community14 Small or concentrated contributor base Maturity57 Maturing project, gaining track record Bus Factor1 Top contributor holds 75% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~63 days Total 3 Last Release 926d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/a3296986413f40064a17152d0ddeb08dec0a900e721545a3c9b04651451d19d9?d=identicon)[2am.](/maintainers/2am.) --- Top Contributors [![2amjsouza](https://avatars.githubusercontent.com/u/142612126?v=4)](https://github.com/2amjsouza "2amjsouza (30 commits)")[![sJonatas](https://avatars.githubusercontent.com/u/9554096?v=4)](https://github.com/sJonatas "sJonatas (10 commits)") --- Tags apiframeworklaravelmailmicroservicephpredisrest-apiphpapiframeworklaravelrestmailMicroservice ### Code Quality TestsPHPUnit Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/2amtech-laravel-mail-api/health.svg) ``` [![Health](https://phpackages.com/badges/2amtech-laravel-mail-api/health.svg)](https://phpackages.com/packages/2amtech-laravel-mail-api) ``` ### Alternatives [unopim/unopim UnoPim Laravel PIM 10.5k2.4k](/packages/unopim-unopim)[bagisto/bagisto Bagisto Laravel E-Commerce 27.6k172.1k9](/packages/bagisto-bagisto)[krayin/laravel-crm Krayin CRM 23.2k33.6k1](/packages/krayin-laravel-crm)[codewithdennis/larament Larament is a time-saving starter kit to quickly launch Laravel 13.x projects. It includes FilamentPHP 5.x pre-installed and configured, along with additional tools and features to streamline your development workflow. 3891.8k](/packages/codewithdennis-larament) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)