包简介

FreshMail API PHP Client

README 文档

README

PHP API Client for Freshmail API V3

This API V3 client covers only sending transactional emails by FreshMail Application. If You want to use any other functions of API use API V2 client.

Requirements

PHP7.2 and above

Installation

Update your composer.json and run composer update

{
    "require": {
        "freshmail/php-api-client": "^1.0"
    }
}

or execute

composer require freshmail/php-api-client

Usage

Sent transactional email

use \FreshMail\Api\Client\Service\Messaging\Mail;
use \FreshMail\Api\Client\Messaging\Mail\MailBag;

$token = 'MY_APP_TOKEN';
$mailService = new Mail($token);

$mail = new MailBag();
$mail->setFrom('from@address.com', 'Office');
$mail->setSubject('That\'s my awesome first mail!');
$mail->setHtml('<html><body><strong>Look!</strong> its working!</body></html>');
$mail->addRecipientTo('recipient email address');

$response = $mailService->send($mail);

Handle with response object

if ($response->isSuccess()) {
    $responseData = $response->getData();    
}

Handle with raw PSR-7 ResponseInterface

$response->getPsr7Response();

Send personalized email

use \FreshMail\Api\Client\Service\Messaging\Mail;
use \FreshMail\Api\Client\Messaging\Mail\MailBag;

$token = 'MY_APP_TOKEN';
$mailService = new Mail($token);

$mail = new MailBag();
$mail->setFrom('from@address.com', 'Office');
$mail->setSubject('Hello $$first_name$$! I\'v got promotion code for You!');
$mail->setHtml('<html><body>Your code is <strong>$$code$$</strong></body></html>');
$mail->addRecipientTo('recipient email address', [
    'first_name' => 'Joshua',
    'code' => 'CODE1234'
]);

$response = $mailService->send($mail);

Send multiply emails

You can send multiple emails by one request. It's much faster than sending one email by one request. In one request You can send up to 100 emails.

use \FreshMail\Api\Client\Service\Messaging\Mail;
use \FreshMail\Api\Client\Messaging\Mail\MailBag;

$token = 'MY_APP_TOKEN';
$mailService = new Mail($token);

$mail = new MailBag();
$mail->setFrom('from@address.com', 'Office');
$mail->setSubject('Hello $$first_name$$! I\'v got promotion code for You!');
$mail->setHtml('<html><body>Your code is <strong>$$code$$</strong></body></html>');

//first recipient
$mail->addRecipientTo('recipient email address', [
    'first_name' => 'Joshua',
    'code' => '10percentDISCOUNT'
]);

//second recipient
$mail->addRecipientTo('second recipient email address', [
    'first_name' => 'Donald',
    'code' => '25percentDISCOUNT'
]);

//third recipient
$mail->addRecipientTo('third recipient email address', [
    'first_name' => 'Abbie',
    'code' => 'FREEshippingDISCOUNT'
]);

$response = $mailService->send($mail);

Send email from template

You can use FreshMail Templates mechanism to optimize requests to API. Additionally You can modify content of Your emails in FreshMail, not modifying the code of Your application.

use \FreshMail\Api\Client\Service\Messaging\Mail;
use \FreshMail\Api\Client\Messaging\Mail\MailBag;

$token = 'MY_APP_TOKEN';
$mailService = new Mail($token);

$mail = new MailBag();
$mail->setFrom('from@address.com', 'Support');
$mail->setSubject('Hello, that\'s my email genereted by template!');
$mail->setTemplateHash('TEMPLATE_HASH');
$mail->addRecipientTo('recipient email address');

$response = $mailService->send($mail);

Send email with attachments

You can sent emails with attachments. You can upload up to 10 files. Weight of all attachments in email can't exceed 10Mb.

use \FreshMail\Api\Client\Service\Messaging\Mail;
use \FreshMail\Api\Client\Messaging\Mail\Base64Attachment;
use \FreshMail\Api\Client\Messaging\Mail\LocalFileAttachment;
use \FreshMail\Api\Client\Messaging\Mail\MailBag;

$token = 'MY_APP_TOKEN';
$mailService = new Mail($token);

//attachment from hard drive
$localFileAttachment = new LocalFileAttachment(
    '/my/local/path/file.extension',
    'optional file name'
);

//attachment from base64 
$base64Attachment = new Base64Attachment(
    'example.txt',
    base64_encode('example content')
);

$mail = new MailBag();
$mail->setFrom('from@address.com', 'Support');
$mail->setSubject('Hello, thats mail with attachments!!');
$mail->setHtml('<html><body><strong>Attachments</strong> in mail</body></html>');
$mail->addRecipientTo('recipient email address');

$mail->addAttachment($localFileAttachment); 
$mail->addAttachment($base64Attachment);

$response = $mailService->send($mail);

Error handling

API throws exceptions for errors that occurred during requests and errors occurred before sending requests.

If request is not sent to server because of wrong API usage, a FreshMail\Api\Client\Exception\ApiUsageException is thrown. This kind of exception means, for example, wrong parameters pass to some methods or passing both content and template in transactional mail, which means request won't be accepted, so API does not make any request.
If request is sent and some network issue occurred (DNS error, connection timeout, firewall blocking requests), a FreshMail\Api\Client\Exception\RequestException is thrown.
If request is sent, a response is received but some server error occurred (500 level http code), a FreshMail\Api\Client\Exception\ServerException is thrown.
If request is sent, a response is received but some client error occurred (400 level http code), a FreshMail\Api\Client\Exception\ClientError is thrown. This error message has getRequest and getResponse methods to receive raw Request nad Response object (implemented by PSR-7 Psr\Http\Message\RequestInterface and Psr\Http\Message\ResponseInterface)

use FreshMail\Api\Client\Exception\ClientError;

try {
    $response = $mailService->send($mail);
} catch (ClientException $exception) {
    echo $exception->getRequest()->getBody();
    echo $exception->getResponse()->getBody();
}

FreshMail\Api\Client\Exception\RequestException, FreshMail\Api\Client\Exception\ClientException and FreshMail\Api\Client\Exception\ServerException extends from FreshMail\Api\Client\Exception\TransferException. FreshMail\Api\Client\Exception\TransferException and FreshMail\Api\Client\Exception\ApiUsageException extends from FreshMail\Api\Client\Exception\GeneralApiException. All exceptions has methods hasRequest, hasResponse.

use FreshMail\Api\Client\Exception\GeneralApiException;

try {
    $response = $mailService->send($mail);
} catch (GeneralApiException $exception) {
    $error = $exception->getMessage();
    if ($exception->hasRequest()) {
        $request = (string) $exception->getRequest()->getBody();
    }
    
    if ($exception->hasResponse()) {
        $response = (string) $exception->getResponse()->getBody();
    }
}

Proxy setup

If You need to configure proxy You can use a custom GuzzleHttp\Client object.

use \FreshMail\Api\Client\Service\Messaging\Mail;

$client = new \GuzzleHttp\Client(
    [
        'proxy' => 'my proxy url'
    ]
);

$token = 'MY_APP_TOKEN';
$mailService = new Mail($token);
$mailService->setGuzzleHttpClient($client);

Logging and debugging

If You need to log or debug Your request You can use 2 features.

PSR-3 Logger Interface

You can use any library that implements PSR-3 Psr\Log\LoggerInterface, example with Monolog below:

use \FreshMail\Api\Client\Service\Messaging\Mail;

$logger = new \Monolog\Logger('myCustomLogger');
$logger->pushHandler(new \Monolog\Handler\StreamHandler('php://stderr', \Monolog\Logger::DEBUG));

$token = 'MY_APP_TOKEN';
$mailService = new Mail($token);
$mailService->setLogger($logger);

Logging by GuzzleHttp Client

To make request API use GuzzleHttp\Client object. If You want You can configure it in any way You want, especially You can enable logging in Client.

use \FreshMail\Api\Client\Service\Messaging\Mail;

$stack = \GuzzleHttp\HandlerStack::create();
$stack->push(
    \GuzzleHttp\Middleware::log(
        new \Monolog\Logger('Logger'),
        new \GuzzleHttp\MessageFormatter('{req_body} - {res_body}')
    )
);

$client = new \GuzzleHttp\Client(
    [
        'handler' => $stack,
    ]
);

$token = 'MY_APP_TOKEN';
$mailService = new Mail($token);
$mailService->setGuzzleHttpClient($client);

freshmail/php-api-client 适用场景与选型建议

freshmail/php-api-client 是一款基于 PHP 开发的 Composer 扩展包，目前已累计 33.21k 次下载、GitHub Stars 达 1，最近一次更新时间为 2019 年 10 月 18 日，在 PHP 生态内属于活跃度较高的组件。

它主要适用于以下技术方向：「mail」「api client」「freshmail」「transactional mail」「freshmail.com」「freshmail.pl」等业务场景。在实际项目中，围绕这些方向常见需要落地的问题包括：接口对接、性能调优、并发安全、与既有框架（Laravel / ThinkPHP / Yii / Webman 等）的兼容适配，以及生产环境的日志埋点与稳定性保障。

我们在过去多个企业项目中使用过 freshmail/php-api-client 或与其功能相近的方案，如果你在选型或落地过程中遇到问题，例如 版本兼容、二次改造、私有化封装、与内部系统对接、生产 BUG 排查，欢迎联系我们协助评估。

围绕 freshmail/php-api-client 我们能提供哪些服务？

定制开发 / 二次开发

基于 freshmail/php-api-client 在你已有业务上做功能扩展、字段裁剪、UI 适配、与内部账号 / 权限 / 日志系统的深度对接。

BUG 修复 & 性能优化

线上偶发问题、内存泄漏、慢查询、并发异常等排查修复；针对高流量场景做缓存、队列、索引层面的调优。

项目外包 & 长期维护

承接完整的项目从需求 → 设计 → 开发 → 上线 → 长期运维；也可按月提供技术保姆服务。

yvsm@zunyunkeji.com QQ：316430983 微信：yvsm316 西安尊云信息科技 · 专注 PHP / Go / 分布式系统研发

与 freshmail/php-api-client 相关的其它包

同方向 / 同关键字的高下载量 PHP Composer 包推荐，方便对比选型：

beebmx/kirby-courier 40

Courier offers a convenient and painless solution for creating emails tailored for your Kirby website.

theodorejb/phaster 6

A PSR-7 compatible library for making CRUD API endpoints

webclient/fake-http-client 2

Mock PSR-18 HTTP client

zimbra-api/mail 2

Mail libraries used by Zimbra Api

ipub/mqtt-client 1

Asynchronous MQTT client built on React

beebmx/kirby-email-plus 2

Email+ extends Kirby's email capabilities by adding support for multiple email services using the same Kirby email API.

freshmail/php-api-client

包简介

关键字：