richardhj / newsletter2go-api
Model based Newsletter2Go API implementation
Installs: 1 598
Dependents: 1
Suggesters: 0
Security: 0
Stars: 1
Watchers: 3
Forks: 2
Open Issues: 1
Requires
- php: ^5.4|^7.0
- richardhj/oauth2-newsletter2go: ~2.0
This package is auto-updated.
Last update: 2024-10-10 20:42:20 UTC
README
This package provides a model based implementation of the Newsletter2Go API. It aims to make complex documentations unnecessary. With its clear structure and extensive PHPDoc, it is really easy to use.
Install
Via Composer
$ composer require richardhj/newsletter2go-api
Usage
Fetch and alter
If you want to fetch items via the API there might be a static function for. Example:
$users = Richardhj\Newsletter2Go\Api\Model\NewsletterUser::findAll(null, $apiCredentials); // Use a PHPDoc comment and profit from auto suggestion /** @var NewsletterUser $user */ foreach ($users as $user) { // What's about naming all users "Doe"? $user->setLastName('Doe'); // Save the user (via the API of course) $user->save(); // $data contains all data fetched for this item $data = $user->getData(); }
$recipients = Richardhj\Newsletter2Go\Api\Model\NewsletterRecipient::findByListAndGroup('abc123', 'xyz987', null, $apiCredentials); var_dump($recipients); foreach ($recipients as $recipient) { $recipient->addToGroup('xyz345'); $recipient->removeFromGroup('asdf12'); }
Api Credentials
ApiCredentials
are mandatory for the api communication. First of all you need the auth_key
that can be found
in the Newsletter2Go back end. The auth_key
is the same for all company's accounts.
Furthermore you either need a user's username
and password
or a user's refresh_token
.
If you rather want to use and save the refresh_token
instead of username and password in your application, you
have to make an initial api authorization call with the username
and password
anyway. Check the
manual of the corresponding OAuth provider to
get to know how to fetch a refresh_token
.
// Use the ApiCredentialsFactory $apiCredentials = ApiCredentialsFactory::createFromUsernameAndPassword('secret_auth_token', 'user@example.org', 'open_sesame'); $apiCredentials = ApiCredentialsFactory::createFromRefreshToken('secret_auth_token', 'secret_users_refresh_token'); // Or simply use ::create() $apiCredentials = ApiCredentialsFactory::create('secret_auth_token', 'secret_users_refresh_token');
Get parameters
When fetching a collection from the api, you can provide a GetParamters
instance. Get parameters allow you to
filter, limit etc. the item collection that will be returned. Example:
$getParams = new Richardhj\Newsletter2Go\Api\Tool\GetParameters(); $getParams ->setExpand(true) ->setFilter('email=like="%@example.org"') ->setOffset(2) ->setLimit(1); $recipients = Richardhj\Newsletter2Go\Api\Model\NewsletterRecipient::findByListAndGroup('abc123', 'xyz987', $getParams, $apiCredentials); var_dump($recipients);
Create
If you want to create items via the API, this is how. Example:
$recipient = new Richardhj\Newsletter2Go\Api\Model\NewsletterRecipient(); $recipient->setApiCredentials($apiCredentials); $recipient ->setListId('abc123') ->setFirstName('John') ->setLastName('Doe') ->setEmail('doe@example.org') ->setGender('m'); // Good to have an id, otherwise the email address will be the primary key and you will not be able to change the email address of a recipient properly $recipient->setId('xyz123'); // Update an existing recipient (when id given or email address known in Newsletter2Go) or create a new recipient $recipient->save();
Delete
For models that implement Newsletter2Go\Api\Model\ModelDeletableInterface
, delete()
is available. Example:
$groups = Newsletter2Go\Api\Model\NewsletterGroup::findByList('abc123', $getParams, $credentials); /** @var NewsletterGroup $group */ foreach ($groups as $group) { $group->delete(); }
Official API documentation
Visit the official API documentation for reference.
License
The GNU Lesser General Public License (LGPL).