2am.tech/laravel-mail-api

Laravel 邮件 API 微服务

维护者

详细信息

github.com/2amigos/laravel-mail-api

主页

源代码

问题

安装: 13

依赖: 0

建议者: 0

安全性: 0

星标: 3

关注者: 12

分支: 1

开放问题: 0

类型:项目

1.0.1 2023-12-20 02:44 UTC

Requires

Requires (Dev)

MIT 8feb8f140f44dc008c8934c12b0a52eeaa3f6672

mailframeworkphprestapilaravelMicroservice

This package is auto-updated.

Last update: 2024-09-20 04:35:21 UTC

README

Laravel Mail API

Build Software License Codacy Badge Quality Codacy Badge Coverage

关于邮件 API 服务

Laravel 邮件 API 是一个电子邮件微服务，用于避免在涉及微服务基础设施的项目中重复配置邮件。

它使用签名 AppKeys 通过请求处理认证。邮件发送器传输接口是使用 Laravel Mail（由 Symfony Mailer 驱动）和 Markdown 邮件通知 来构建，以增强电子邮件布局配置。

为了以高效的响应时间发送电子邮件，Laravel 邮件 API 使用 Laravel 队列 在后台执行任务。我们已经为 Redis（Predis）连接配置了驱动程序。如果需要，您可以配置其他驱动程序。

最后，它使用 Laravel 本地化 进行内容国际化，并使用 Laravel 日志 进行日志记录。

安装

$ composer create-project 2am.tech/laravel-mail-api app

配置

Docker 容器配置

通过 Laravel Sail 提供了 Docker 镜像。

您可以配置一个 Sail 命令的 shell 别名，以便更容易访问。

请参阅 Sail 文档，了解如何在您的应用程序容器中执行命令的更多信息。

要启动/停止 Docker 容器，请使用以下命令：为了能够使用 Docker 容器，您需要首先安装依赖项。为此，您必须执行给定的命令

$ 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

如果您使用 Laravel Sail，请参阅 .env.sail 以获取 Redis 连接字符串。

.env.example 文件提供了项目正确运行所需的基本结构。将其内容复制到 .env 文件中。

应用程序配置

如前所述，我们使用签名 AppKeys 进行请求认证。

首先，您必须在 ./config/laravel-mail-api 中的 AccessTokens 部分定义您的访问令牌（AppKey 和 AppSecret）。

我们已经提供了一个示例访问密钥。

# register access token
...
'accessTokens' => [
    'access-key-user-1' => [
        'appKey' => 'jwYitJJOop2v',
        'appSecret' => 'token',
    ],
   ... 
];

您可以注册您微服务所需的所有访问令牌。

访问令牌定义后，我们只需要对其进行签名并将其值添加到请求头中。

访问令牌签名算法

定义一个哈希算法来创建一个哈希令牌。默认为 sha512。您可以在 .env 文件中添加 HASH_SIGNATURE 来定义它。

HASH_SIGNATURE=sha512

要为您访问令牌创建签名，请按照以下步骤操作

获取当前的 UTC 格式的 ISO-8601 时间戳。

$ date -u +'%Y-%m-%dT%H:%M:%S.%3NZ'

# ouputs date format
$ 2023-08-10T04:32:25.620Z

然后，使用您的 AppSecret 作为哈希密码，简单地将 AppKey 与获取的时间戳进行哈希。

signature: HASH-HMACK( AppKey + timestamp, AppSecret )

# with our sample values
signature: HASH-HMACK( 'jwYitJJOop2v' + '2023-08-10T04:32:25.620Z', 'token' )

# output
cb64bbccdff25dcaba24e4c029aa54d99522a3e2e70e5be7be1b48dd8816b4e05b0102f2a2775c895ac73f649b45f6f97f755a112a9f4a206e4053128fc5ada9

为了测试目的，我们创建了一个用于签名创建的命令

$ php artisan app:create-signature

邮件传输配置

您还必须在.env文件中配置您的邮件传输。该项目使用SMTP构建。Laravel Mail提供了一种简单的方式来配置项目所需的驱动程序。

这是一个示例SMTP驱动程序配置

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

用法

为了运行应用程序，Laravel提供了方便的内置命令serve

$ php artisan serve

# or on Sail
$ ./vendor/bin/sail php artisan serve

此命令在http://127.0.0.1:8000上运行您的应用程序。如果您通过Laravel Sail运行此命令，应用程序将在端口80上运行，而不是http://127.0.0.1。

端点

API有一个端点：/api/email/send。

为了简化测试过程，已经提供了一份名为Laravel Mail API的Postman集合。

/api/email/send

为了使认证机制正常工作，我们必须添加以下头部信息

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

然后您可以发送带有以下参数的multipart/form-data请求

  • from
  • 发送者 (可选)
  • to
  • 接收者 (可选)
  • subject
  • language (可选，默认为en)
  • template (可选，默认在应用程序中定义)
  • attachments[] (可选)

以下是一个示例请求

curl --location 'https://: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"'

完成。现在，您的新消息已经在队列中，准备分发。为此，您只需运行此命令即可

$ php artisan queue:work

# or on sail
$ ./vendor/bin/sail php artisan queue:work

电子邮件附件

端点/api/email/send对附件的mimetype进行验证。

默认情况下，应用程序将允许PDF和任何Image mimetypes。

您可以轻松设置所需的mimetype数组，甚至设置字符串'*'以允许任何mimetype。例如，要允许任何文件mimetype，您只需更改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', '*'),
];

自定义

如前所述，此服务使用Markdown邮件通知来增强电子邮件布局配置。您可以在resources/views/vendor/mail/html中找到已发布的Markdown模板文件。

电子邮件正文在模板文件中设置。它已经集成了Laravel本地化，以提供国际化功能。

您可以通过查看默认模板recources/views/templates/hello-world.blade.php和密码模板resruoces\views\templates\password.blade.php来参考，因为它们已经编写了本地化。

您可以通过在.env文件中声明常量TOKEN_TIME（以分钟为单位）来定义令牌的有效期。默认为60。

您可以通过声明DEFAULT_TEMPLATE来定义默认电子邮件模板，默认为hello-world，并通过声明LANGUAGE常量（默认为en）来定义默认语言。

部署

虽然队列工作命令很方便，使在测试应用程序时消耗队列变得非常容易，但强烈建议在部署到生产环境时使用Supervisor。

Laravel有一篇很好的指南，介绍了如何配置 Supervisor。

无服务器部署到AWS Lambda

此项目使用Bref框架来实现无缝部署到AWS Lambda。

为此，它有一个很小的依赖项列表

  • Node.js 14.0+
  • Serverless框架
  • 以及，一个AWS账户（密钥和秘密）。

要安装Serverless框架

$ npm install -g serverless

安装Serverless插件依赖

$ npm install

然后，为Serverless框架设置AWS凭证

$ serverless config credentials --provider aws --key "key" --secret "secret"

您可以在文件serverless.yml中更改项目名称，使其与您的项目名称匹配，就在第一行

service: laravel-mail-api

在实际部署之前的最后一步是清除本地缓存文件

$ php artisan config:clear

还有，然后

$ serverless deploy

一旦过程完成，您将收到AWS Lambda上创建的端点、函数和作业提示！

贡献

请参阅CONTRIBUTING以获取详细信息。

许可

BSD许可证（BSD）。请参阅许可文件以获取更多信息/

2am.tech

Web开发从未如此有趣！

https://2am.tech/