fazland/mailup-rest-client

Unofficial MailUp Rest Client

dev-master / 1.0.x-dev 2020-01-14 10:56 UTC

This package is auto-updated.

Last update: 2024-10-14 21:38:04 UTC


README

Build Status Scrutinizer Code Quality Code Coverage

Fazland's MailUp Rest Client is an unofficial PHP Rest Client for the Email and SMS GatewayProvider MailUp.

Requirements

  • php >= 7.0
  • php-http/client-implementation >= 1.0
  • php-http/discovery >= 1.0
  • php-http/message >= 1.0
  • php-http/message-factory >= 1.0
  • psr/http-message >= 1.0
  • psr/http-message-implementation >= 1.0
  • symfony/options-resolver >= 2.7

Installation

The suggested installation method is via composer:

$ composer require fazland/mailup-rest-client

Using MailUp Rest Client

It's really simple. First of all, configuration!

Configuration

The mandatory configuration parameters are:

  • username
  • password
  • client_id
  • client_secret

The only optional parameter is cache_dir. If set, the access token are saved in that path.

Just create a Context object passing to the constructor the parameters as an array:

use Fazland\MailUpRestClient\Context;

$config = [
    'username' => 'your_username',
    'password' => 'your_password',
    'client_id' => 'your_client_id',
    'client_secret' => 'your_client_secret',
    'cache_dir' => 'path_to_your_cache_dir', // Optional
];

$httpClient = new HttpClientImplementation();

$context = new Context($config, $httpClient);

Mailing Lists

To create a MailingList you can follow this example. Please, refer to the MailUp official API docs for the $params array.

use Fazland\MailUpRestClient\MailingList;

$email = "owner_of_the_list@email.com";
$listName = "list_name";
$params = [
    // your params...
];

$list = MailingList::create($context, $listName, $email, $params);

You can also obtain all the existing lists in your MailUp account by calling the static method MailingList::getAll():

use Fazland\MailUpRestClient\MailingList;

$lists = MailingList::getAll($context);

Once you have an instance of MailingList, you can do the following operations:

  • add a Recipient
use Fazland\MailUpRestClient\Recipient;

$list->addRecipient(new Recipient('Aragorn', 'aragorn@gondor.com', '3333333333', '+39'));
  • update a Recipient
use Fazland\MailUpRestClient\Recipient;

$list->updateRecipient(new Recipient('Aragorn', 'aragorn@gondor.com', '3334444444', '+39'));
  • remove a Recipient
use Fazland\MailUpRestClient\Recipient;

$list->removeRecipient(new Recipient('Aragorn', 'aragorn@gondor.com', '3333333333', '+39'));
  • find a Recipient by its email
$recipient = $list->findRecipient('aragorn@gondor.com'); // null returned if current email was not found
  • retrieve all the groups of the current list:
$groups = $list->getGroups();
  • count how many recipients are in the list (default is subscribed, but you can search for unsubscribed o pending statuses too):
$countRecipients = $list->countRecipients(); // equal to $list->countRecipients(Recipient::STATUS_SUBSCRIBED);
// OR
$countRecipients = $list->countRecipients(Recipient::STATUS_UNSUBSCRIBED);
// OR
$countRecipients = $list->countRecipients(Recipient::STATUS_PENDING);
  • get recipients paginated (you can specify the same status used in MailingList::countRecipients()):
$recipients = $list->getRecipientsPaginated($pageNumber, $pageSize);
  • least, but not last, import an array of Recipient objects:
$list->import($recipients);

Groups

Each MailingList can be split into multiple groups. The operations available are the following:

  • retrieve or modify its name:
$group->getName();
$group->setName('Gondor Army');
  • retrieve or modify its notes:
$group->getNotes();
$group->setNotes('10.000 knights and 20.000 peons');
  • prevent or allow deletion:
$group->isDeletable();
$group->setDeletable(true);
  • delete:
$group->delete();
  • add, remove or retrieve the recipients:
use Fazland\MailUpRestClient\Recipient;

$legolas = new Recipient('Legolas Thranduilion', 'legolas@lothlorien.elf', '3334444444', '+39');
$group->addRecipient($legolas);
$group->removeRecipient($legolas);
$lothlorienCitizens = $group->getRecipients();

Contributing

Contributions are welcome. Feel free to open a PR or file an issue here on GitHub!

License

MailUp Rest Client is licensed under the MIT License - see the LICENSE file for details