README

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

fazland / mailup-rest-client

Maintainers

Details