PHPackages                             freshmail/php-api-client - 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. [Mail & Notifications](/categories/mail)
4. /
5. freshmail/php-api-client

ActiveLibrary[Mail & Notifications](/categories/mail)

freshmail/php-api-client
========================

FreshMail API PHP Client

1.6.1(1y ago)132.4k↓16.7%6[2 issues](https://github.com/FreshMail/php-api-client/issues)[1 PRs](https://github.com/FreshMail/php-api-client/pulls)1Apache-2.0PHPPHP ^7.2 || ^8.0

Since Oct 18Pushed 1y ago3 watchersCompare

[ Source](https://github.com/FreshMail/php-api-client)[ Packagist](https://packagist.org/packages/freshmail/php-api-client)[ RSS](/packages/freshmail-php-api-client/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (6)Versions (14)Used By (1)

PHP API Client for Freshmail API V3

[Official API V3 Documentation](https://freshmail.pl/dokumentacja-rest-api-v3/docs/messaging/emails/)

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](https://github.com/FreshMail/REST-API).

Requirements
============

[](#requirements)

- PHP7.2 and above

Installation
============

[](#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
=====

[](#usage)

Sent transactional email
------------------------

[](#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('Look! its working!');
$mail->addRecipientTo('recipient email address');

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

Handle with response object
---------------------------

[](#handle-with-response-object)

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

Handle with raw [PSR-7 ResponseInterface](https://www.php-fig.org/psr/psr-7/#33-psrhttpmessageresponseinterface)
----------------------------------------------------------------------------------------------------------------

[](#handle-with-raw-psr-7-responseinterface)

```
$response->getPsr7Response();
```

Send personalized email
-----------------------

[](#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('Your code is $$code$$');
$mail->addRecipientTo('recipient email address', [
    'first_name' => 'Joshua',
    'code' => 'CODE1234'
]);

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

Send multiply emails
--------------------

[](#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('Your code is $$code$$');

//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
------------------------

[](#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
---------------------------

[](#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('Attachments in mail');
$mail->addRecipientTo('recipient email address');

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

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

Error handling
==============

[](#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
===========

[](#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
=====================

[](#logging-and-debugging)

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

PSR-3 Logger Interface
----------------------

[](#psr-3-logger-interface)

You can use any library that implements [PSR-3](https://www.php-fig.org/psr/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
----------------------------

[](#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);
```

###  Health Score

37

—

LowBetter than 83% of packages

Maintenance18

Infrequent updates — may be unmaintained

Popularity31

Limited adoption so far

Community17

Small or concentrated contributor base

Maturity70

Established project with proven stability

 Bus Factor1

Top contributor holds 56.3% 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 ~208 days

Recently: every ~304 days

Total

10

Last Release

531d ago

PHP version history (2 changes)1.1.0PHP ^7.0

1.4.0PHP ^7.2 || ^8.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/88144ec17acb17a03afc8cfb25af50bd56d560c4f15517db86ab26a4b2882169?d=identicon)[FreshMail](/maintainers/FreshMail)

---

Top Contributors

[![ankalagon](https://avatars.githubusercontent.com/u/532333?v=4)](https://github.com/ankalagon "ankalagon (9 commits)")[![grzesiekgorczyca](https://avatars.githubusercontent.com/u/8577651?v=4)](https://github.com/grzesiekgorczyca "grzesiekgorczyca (5 commits)")[![scardinius](https://avatars.githubusercontent.com/u/8309610?v=4)](https://github.com/scardinius "scardinius (2 commits)")

---

Tags

mailapi clientfreshmailtransactional mailfreshmail.comfreshmail.pl

### Embed Badge

![Health badge](/badges/freshmail-php-api-client/health.svg)

```
[![Health](https://phpackages.com/badges/freshmail-php-api-client/health.svg)](https://phpackages.com/packages/freshmail-php-api-client)
```

###  Alternatives

[shopware/platform

The Shopware e-commerce core

3.3k1.5M3](/packages/shopware-platform)[zbateson/mail-mime-parser

MIME email message parser

54149.2M79](/packages/zbateson-mail-mime-parser)[tempest/framework

The PHP framework that gets out of your way.

2.1k23.1k9](/packages/tempest-framework)[shopware/core

Shopware platform is the core for all Shopware ecommerce products.

595.2M386](/packages/shopware-core)[ec-cube/ec-cube

EC-CUBE EC open platform.

78527.0k1](/packages/ec-cube-ec-cube)[coconutcraig/laravel-postmark

Laravel package for sending mail via the Postmark API

2152.9M1](/packages/coconutcraig-laravel-postmark)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)