{"id":19337896,"url":"https://github.com/2amigos/laravel-mail-api","last_synced_at":"2025-04-23T01:31:07.253Z","repository":{"id":188493209,"uuid":"671948841","full_name":"2amigos/laravel-mail-api","owner":"2amigos","description":"A microservice to send emails based on templates.","archived":false,"fork":false,"pushed_at":"2023-12-20T02:46:21.000Z","size":1069,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":12,"default_branch":"main","last_synced_at":"2025-04-02T06:21:37.513Z","etag":null,"topics":["api","framework","laravel","mail","microservice","php","redis","rest-api"],"latest_commit_sha":null,"homepage":"https://2am.tech/","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/2amigos.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"contributing.md","funding":null,"license":"license.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2023-07-28T14:16:41.000Z","updated_at":"2024-09-14T05:10:18.000Z","dependencies_parsed_at":"2023-08-15T15:50:15.194Z","dependency_job_id":null,"html_url":"https://github.com/2amigos/laravel-mail-api","commit_stats":null,"previous_names":["2amigos/laravel-mail-api"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/2amigos%2Flaravel-mail-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/2amigos%2Flaravel-mail-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/2amigos%2Flaravel-mail-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/2amigos%2Flaravel-mail-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/2amigos","download_url":"https://codeload.github.com/2amigos/laravel-mail-api/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250352224,"owners_count":21416458,"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":["api","framework","laravel","mail","microservice","php","redis","rest-api"],"created_at":"2024-11-10T03:15:44.923Z","updated_at":"2025-04-23T01:31:06.265Z","avatar_url":"https://github.com/2amigos.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Laravel Mail API\n\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://2am.tech/our-work/open-source\" target=\"_blank\"\u003e\n        \u003cimg src=\"./assets/img/mail-api-service.png\" width=\"100%\" target=\"_blank\" alt=\"Laravel Mail API\"\u003e\n    \u003c/a\u003e\n\u003c/p\u003e\n\n\n[![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)\n[![Software License](https://img.shields.io/badge/license-BSD-brightgreen.svg?style=flat-square)](LICENSE.md)\n[![Codacy Badge Quality](https://app.codacy.com/project/badge/Grade/0a7b90cb75054113b3977186ee89cc33)](https://app.codacy.com?utm_source=gh\u0026utm_medium=referral\u0026utm_content=\u0026utm_campaign=Badge_grade)\n[![Codacy Badge Coverage](https://app.codacy.com/project/badge/Coverage/0a7b90cb75054113b3977186ee89cc33)](https://app.codacy.com?utm_source=gh\u0026utm_medium=referral\u0026utm_content=\u0026utm_campaign=Badge_coverage)\n\n## About Mail API Service\n\nLaravel Mail API is an email microservice to avoid having to configure mail over and over\non projects involving microservices infrastructure.\n\nIt uses Signed AppKeys to handle the authentications through requests.\nThe 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))\nwith [Markdown Mail Notifications](https://laravel.com/docs/10.x/notifications#markdown-mail-notifications) to enhance the email layout configuration.\n\nTo accomplish dispatching emails with an efficient response time, Laravel Mail API uses [Laravel Queues](https://laravel.com/docs/10.x/queues)\nto 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.\n\nFinally, 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) \nfor logging. \n\n## Install\n```bash\n$ composer create-project 2am.tech/laravel-mail-api app\n```\n\n## Configuration\n\n### Docker Container Configuration\n\nA docker image was provided through [Laravel Sail](https://laravel.com/docs/10.x/sail#main-content).\n\nYou 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.\n\nPlease, 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).\n\nTo start up/stop the docker container, use the following commands:\nTo be able to use the docker container, you need to first install the dependencies.\nTo achieve that, you must execute the given command:\n\n```bash\n$ docker run --rm \\\n    -u \"$(id -u):$(id -g)\" \\\n    -v \"$(pwd):/var/www/html\" \\\n    -w /var/www/html \\\n    laravelsail/php82-composer:latest \\\n    composer install --ignore-platform-reqs\n```\n\n```SH\n// to start up the container\n$ ./vendor/bin/sail up -d\n\n# to stop the container\n$ ./vendor/bin/sail stop\n```\n\nIf you're using Laravel Sail, refer to **.env.sail** for redis connection strings.   \n\nThe **.env.example** file gives the basic structure your project must have in order to run the service properly. Copy its content to **.env** file.\n\n### Application Configuration\n\nAs mentioned before, we're using Signed AppKeys for requests authentication.\n\nFirst, you have to define you're Access Token (AppKey and AppSecret) on \n`./config/laravel-mail-api`, on `AccessTokens` section.\n\nWe already provided a sample access key.\n\n```php\n# register access token\n...\n'accessTokens' =\u003e [\n    'access-key-user-1' =\u003e [\n        'appKey' =\u003e 'jwYitJJOop2v',\n        'appSecret' =\u003e 'token',\n    ],\n   ... \n];\n```\n\nYou can register as many access token it's necessary for your microservices.\n\nWith the access token defined, we just need to sign it to and add its values\nto the request header.\n\n### Access Token Sign Algorithm\n\nDefine a hash algorithm to create a hashed token. The default is `sha512`.\nYou can define it on by adding `HASH_SIGNATURE` on the `.env` file:\n\n``\nHASH_SIGNATURE=sha512\n``\n\nTo create a signature for you access token, you follow this steps:\n\nGet the current timestamp (on UTC) on ISO-8601 format.\n\n```bash\n$ date -u +'%Y-%m-%dT%H:%M:%S.%3NZ'\n\n# ouputs date format\n$ 2023-08-10T04:32:25.620Z\n```\n\nThen, simple hash your AppKey with the gotten timestamp, using your AppSecret as the \nhash password.\n\n```bash\nsignature: HASH-HMACK( AppKey + timestamp, AppSecret )\n\n# with our sample values\nsignature: HASH-HMACK( 'jwYitJJOop2v' + '2023-08-10T04:32:25.620Z', 'token' )\n\n# output\ncb64bbccdff25dcaba24e4c029aa54d99522a3e2e70e5be7be1b48dd8816b4e05b0102f2a2775c895ac73f649b45f6f97f755a112a9f4a206e4053128fc5ada9\n```\n\nA command was created to help the signature creation, for testing purposes:\n\n```bash\n$ php artisan app:create-signature\n```\n\n### Email Transport Configuration\nYou must configure your mailer transport on .env file as well.\nThis project was built using SMTP. Laravel Mail provides an easy way to [configure](https://laravel.com/docs/10.x/mail#configuration)\nthe driver your project needs.\n\nThis is a sample SMTP Driver configuration:\n```\nMAIL_MAILER=smtp\nMAIL_HOST={smtp-server}\nMAIL_PORT={smtp-port}\nMAIL_USERNAME={smtp-mailer-email-address}\nMAIL_PASSWORD={smtp-mailer-email-password{\nMAIL_ENCRYPTION=tls\n```\n\n## Usage\n\nTo serve the application, Laravel provides the handy built in command **serve**\n```SH\n$ php artisan serve\n\n# or on Sail\n$ ./vendor/bin/sail php artisan serve\n```\n\nThis command serve your application at [http://127.0.0.1:8000](http://127.0.0.1:8000).\nIf you run the command through Laravel Sail, the application will be served on port 80 instead [http://127.0.0.1](http://127.0.0.1).\n\n## Endpoints\n\nThe API has one endpoint: `/api/email/send`.\n\nA postman collection `Laravel Mail API` has been served to simplify the testing process.\n\n### /api/email/send\n\nIn order to have the authentication mechanism working, we must add the following headers:\n```bash\nAuthentication: Bearear {signature}\nts: {timestap (used to sign the appKey)}\naccessToken: {your access token}\n\n# using our sample values\nAuthentication: Bearear cb64bbccdff25dcaba24e4c029aa54d99522a3e2e70e5be7be1b48dd8816b4e05b0102f2a2775c895ac73f649b45f6f97f755a112a9f4a206e4053128fc5ada9\nts: 2023-08-10T04:32:25.620Z\naccessToken: access-key-user-1\n```\n\nThen you can send `multipart/form-data` request with the following parameters:\n\n-  from\n-  sender *(optional)*\n-  to\n-  receiver *(optional)*\n-  subject\n-  language *(optional, default=en)*\n-  template *(optional, default defined on the application)*\n-  attachments[] *(optional)*\n\nHere is a sample request:\n\n```SH\ncurl --location 'http://localhost:8000/api/email/send' \\\n--header 'accessKey: tests' \\\n--header 'ts: 2023-08-10T04:56:50+00:00' \\\n--header 'Authorization: Bearer a7ef7032999db841c75a7a2de4d40106e6de19b7c269b722f81bc51a1f713f6642d25e3bc25af7b04f9a385ef8f9c9ed346e029d0262cbc61dde2f640d0f8c48' \\\n--form 'from=\"test@mail.com\"' \\\n--form 'to=\"receiver@email.com\"' \\\n--form 'sender=\"2am.tech\"' \\\n--form 'receiver=\"Amigo OSS\"' \\\n--form 'subject=\"test api\"'\n```\n\nDone. Now your new message is on the queue, ready to be dispatched. To achieve that, \nyou just need to run this command:\n\n```SH\n$ php artisan queue:work\n\n# or on sail\n$ ./vendor/bin/sail php artisan queue:work\n```\n\n#### Email Attachments\n\nThe `/api/email/send` endpoint apply validations for attachments mimetypes.\n\nBy default, the application will allow `PDF` and any `Image` mimetypes.\n\nYou can easily set an array of your needed mimetypes, or even set a string `'*'` to allow any mimetype.\ne.g. to allow any file mimetype, you just need to change this line on `config/laravel-mail-api.php`:\n\n```php\nuse Laravel\\Sanctum\\PersonalAccessToken;\n\n// from this \nreturn [\n    ...\n    'attachmentsAllowedMimetypes' =\u003e env('ATTACHMENT_MIMETYPES', ['application/pdf', 'image/*']),\n];\n\n// to this\nreturn [\n    ...\n    'attachmentsAllowedMimetypes' =\u003e env('ATTACHMENT_MIMETYPES', '*'),\n]; \n```\n\n### Customization\n\nAs mentioned before, this service uses [Markdown Mail Notifications](https://laravel.com/docs/10.x/notifications#markdown-mail-notifications) to enhance the email layout configuration.\nYou can find the template files for Markdown published at `resources/views/vendor/mail/html`.\n\nThe email body is set on template files. It already has [Laravel Localization](https://laravel.com/docs/10.x/localization#main-content) to provide\nan internationalization feature to it.\n\nYou can check the default template at `recources/views/templates/hello-world.blade.php` and \nthe password template at `resruoces\\views\\templates\\password.blade.php` for reference, as they've been written\nwith localization already.\n\nYou 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.\n\nYou can define the default email template declaring `DEFAULT_TEMPLATE`, where the default is `hello-world` and the default language by\ndeclaring the `LANGUAGE` constant (default `en`).\n\n### Deploying\n\nAlthough the queue work command is handy and makes it really easy to consume the queue while testing the application,\nbut it's extremely recommended to use [Supervisor](http://supervisord.org/) when deploying to production.\n\nLaravel has a nice guide to properly [configure](https://laravel.com/docs/10.x/queues#supervisor-configuration) the Supervisor.\n\n## Serverless deployment to AWS Lambda\n\nThis project uses [Bref](https://bref.sh/) framework to empower a smoothly deployment to\nAWS Lambda.\n\nIt has a tiny list of dependencies to achieve that:\n\n- Node.js 14.0+\n- [Serverless](https://www.serverless.com/framework/docs) framework\n- and, an AWS account (key and secret).\n\nTo install the Serverless framework:\n\n```bash\n$ npm install -g serverless\n```\n\nInstall Serverless plugin dependency:\n```bash\n$ npm install\n```\n\nAnd them, setup the AWS credentials for the Serverless framework:\n```bash\n$ serverless config credentials --provider aws --key \"key\" --secret \"secret\"\n```\n\nYou can change the project name on file `serverless.yml` to match your project name,\nright on the first line:\n\n```yml\nservice: laravel-mail-api\n```\n\nLast step before the actual deployment is to clear local cashed files:\n```bash\n$ php artisan config:clear\n```\n\nand, them:\n```bash\n$ serverless deploy\n```\n\nOnce the process is finished, you will be prompted with the endpoint,\nfunctions and jobs created on AWS Lambda!\n\n## Contributing\n\nPlease, see [CONTRIBUTING](./contributing.md) for details.\n\n## License\nThe BSD License (BSD). Please see [License File](./license.md) for more information/\n\n\u003e [![2am.tech](https://avatars.githubusercontent.com/u/3440791?s=200\u0026v=4)](https://2am.tech/)\n\nWeb development has never been so fun!\n\n[https://2am.tech/](https://2am.tech/)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F2amigos%2Flaravel-mail-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F2amigos%2Flaravel-mail-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F2amigos%2Flaravel-mail-api/lists"}