README

MailMerge旨在提供一组API，用于使用不同的邮件服务提供商（如mailgun、pepipost和sendgrid）发送各种类型的电子邮件（包括批量邮件和单封邮件）。它还定义了使用不同邮件服务重新发送失败邮件的策略。

需求

• PHP >= 7.4
• Laravel >= 6.0
• Redis

MailMerge使用Redis保存事件和日志，因此您必须在您的服务器上安装Redis。

安装

composer require ahmedwaleed/mailmerge

MailMerge将自动使用包发现注册自身。

Composer完成后，运行以下命令，它将迁移mailmerge迁移

php artisan mailmerge:migrate

配置包

您可以使用以下命令发布配置文件

php artisan vendor:publish --tag="mailmerge-config"

此文件的内容将在config/mailmerge.php中发布

<?php
return [
    /*
    |--------------------------------------------------------------------------
    | MailMerge Path
    |--------------------------------------------------------------------------
    |
    | This is the URI prefix where Wink will be accessible from. Feel free to
    | change this path to anything you like.
    |
    */
    'path' => env('MAILMERGE_PATH', 'mailmerge'),

    /*
    |--------------------------------------------------------------------------
    | MailMerge Services Credentials
    |--------------------------------------------------------------------------
    |
    */
    'services' => [
        'default' => env('DEFAULT_SERVICE', 'mailgun'),
        'mailgun' => [
            'api_key' => env('MAILGUN_API_KEY'),
            'api_domain' => env('MAILGUN_API_DOMAIN'),
            'api_endpoint' => env('MAILGUN_API_ENDPOINT', 'https://api.mailgun.net'),
            'api_base_url' => env('MAILGUN_API_BASE_URL'),
        ],
        'pepipost' => [
            'api_key' => env('PEPIPOST_API_KEY'),
            'api_endpoint' => env('PEPIPOST_API_ENDPOINT'),
        ],
        'sendgrid' => [
            'api_key' => env('SENDGRID_API_KEY'),
            'api_endpoint' => env('SENDGRID_API_ENDPOINT'),
        ],
    ],

    /*
    |--------------------------------------------------------------------------
    | MailMerge Middleware Group
    |--------------------------------------------------------------------------
    |
    | This is the middleware group that mailmerge uses for package web routes.
    |
    */
    'middleware_group' => env('MAILMERGE_MIDDLEWARE_GROUP', 'web'),
];

请设置配置文件中指定的所有服务的所需环境变量。'default' => env('DEFAULT_SERVICE', 'mailgun')为此选项设置默认服务，当使用mailmerge API而未明确指定服务时，将使用此服务。

用法

该包已注册您需要的所有API端点，运行php artisan route:list以查看所有可用的端点。

身份验证

MailMerge使用非常简单的身份验证方法，您只需在请求头中传递一个授权签名即可。

{
    "signature": "90gMPhN7Q3bQYJgFGZufYo7y6DLSSDDurEvFO4EFksA="
}

发送单封电子邮件消息

• API端点

/api/mails/message

• 示例请求参数

{
    "from": "john.snow@thewall.north",
    "to": "john.snow@behindthewall.north",
    "subject": "Hi John",
    "body": "The winters is comming..."
}

• 示例响应

{ 
   "status":200,
   "message":"Email has been sent successfully."
}

• 示例代码

$payload = [
    'from' => 'john.snow@thewall.north',
    'to' => 'john.snow@behindthewall.north',
    'subject' => 'Hi John',
    'body' => 'The winters is comming...'
];

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, "http://domain.com/api/mails/message");
        
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "signature: 80PhN7Q3bQFSDFDSF333fYo7y6DLSSDDKKDK885dvFO4EFksA=" // your auth signature here
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($payload));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$server_output = curl_exec($ch)

发送批量（批量电子邮件）消息

• API端点

/api/mails/batch

• 示例请求参数

{ 
   "recipients":[ 
      { 
         "email": "john.doe@example.com",
         "attributes": {
            "first":"John",
            "last":"Doe",
            "id":"1"
         }
      },
      {
        "email": "sally.doe@example.com",
         "attributes": {
            "first":"sally",
            "last":"Doe",
            "id":"2"
         }
      }
   ],
   "from":"janedoe@example.com",
   "subject":"Hey <%attribute.first%>",
   "body":"If you wish to unsubscribe,click https://domain.com/unsubscribe/<%attribute.id%>"
}

• 示例响应

{ 
   "status":200,
   "message":"Batch message processed successfully."
}

• 示例代码

$payload = [
    'from' => 'john.snow@thewall.north',
    'recipients' => [
            [
                'email' => 'john_doe@example.com',
                'attributes' => [
                'first' => 'john',
                'last' => 'doe'
            ],
            [
                'email' => 'jane_doe@example.com',
                'attributes' => [
                'first' => 'jane',
                'last' => 'doe'
            ]
        ]
    ],
    'subject' => 'Hi <%attribute.first%>',
    'body' => 'This this test body with last name <%attribute.last%>.'
];

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, "http://domain.com/api/mails/batch");
        
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "signature: 80PhN7Q3bQFSDFDSF333fYo7y6DLSSDDKKDK885dvFO4EFksA="
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($payload));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$server_output = curl_exec($ch)

服务

您可以在API头中指定要用于发送消息的服务。例如

curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "API-SERVICE: sendgrid", // suported (mailgun, pepipost, sendgrid)
]);

cc, bcc

邮件合并还允许您在消息中添加抄送(Cc)和暗送(Bcc)，您可以在请求体中添加这些内容。例如。

$payload = [
    // ...
    "cc": "cc1@example.com,cc2@example.com",
    "bcc": "bcc1@example.com,bcc2@example.com",
    // ...
];

附件

使用邮件合并，您可以与批量消息一起发送一个或多个附件。

$payload = [
    // ...
    'attachments' = [
        'https://site.com/uploads/sample1.pdf',
        'https://site.com/uploads/sample2.pdf'
    ],
    // ...
];

• 批量邮件模板

由于MSP的集成方式不同，邮件合并使用自己的电子邮件占位符模板来处理收件人自定义属性（变量），因此您无需担心不同服务的语法。

• 语法 <% attribute.custom_attribute_name %>
• 示例

'recipients' => [
    [
        'email' => 'jane_doe@example.com',
        'attributes' => [
        'id' => '1',
        'first' => 'jane',
        'last' => 'doe'
    ]
]

Subject: Hey <%attribute.first%> <%attribute.last%>  <%attribute.id%>

重新发送批量消息

• API端点

/resend-batch

发送批量消息可能需要用户花费较长时间，您可能需要花时间安排所有要作为批量消息发送的收件人名单，如果您的批量消息失败怎么办？与其每次都重新开始这项繁重的工作，现在使用邮件合并，您可以使用不同的服务（Mailgun、Pepipost、Sendgrid）重新发送您的批量消息。邮件合并保存了您发送的所有批量消息，以便在系统故障或邮件失败数量过多的情况下，您可以在将来重试该批量消息。当您重试或重新发送批量消息时，它只处理发送上一批次失败的收件人的逻辑，因此您可以多次重试该批量消息，直到所有邮件都成功发送。

邮件合并提供处理批量消息的默认视图。 但是，您可以按需修改它。您可以使用以下命令发布邮件合并重新发送批量消息的默认视图。

php artisan vendor:publish --tag='mailmerge-views' --force

一旦视图发布，您可以在resources/views/vendors/mailmerge目录中找到它。

日志记录

MailMerge为所有支持电子邮件服务提供集中式日志系统，使用webhooks支持。MailMerge为每个服务注册端点，以便您可以将该URL添加到您的邮件API webhook设置中。您可以在以下链接中找到有关webhooks的相关文档：mailgun、pepipost、sendgrid。

每当有新的日志时，您的邮件服务将触发该webhook URL，MailMerge将处理该请求并将该日志保存到redis服务器。

获取日志

• 请求查询参数

• 项目（可选）：

/api/logs?items=100

默认情况下，API将返回10个项目，但您可以通过查询中的items参数获取所需数量的项目。

• 服务（必需）：

/api/logs?service=mailgun

• 示例响应

{
    'original_response': {
        //..
    },
    'nomalized_response': {
        //..
    },
}

• 原始响应：包括来自邮件服务的原始有效载荷。

• 规范化响应：将在多个服务中保持一致的规范化响应。

许可证

MailMerge遵循MIT许可证。