From 9a9955f25011d1b9fc57c335d0273e14f032f01e Mon Sep 17 00:00:00 2001 From: mbeckerle Date: Fri, 23 Jun 2023 21:09:08 +0200 Subject: [PATCH 1/6] Added method to retrieve thumbnails of CMS2 mailings --- CHANGELOG | 4 ++++ src/mailings/MailingsService.php | 15 +++++++++++++++ version.txt | 4 ++-- 3 files changed, 21 insertions(+), 2 deletions(-) diff --git a/CHANGELOG b/CHANGELOG index c8cdd6f..27d2af9 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -1,3 +1,7 @@ +Date 2023-06-30 +Version 1.9.8 +- Added method to retrieve thumbnails of CMS2 mailings + Date 2023-05-11 Version 1.9.7 - Added method to update transaction types diff --git a/src/mailings/MailingsService.php b/src/mailings/MailingsService.php index 179a882..f573cd9 100644 --- a/src/mailings/MailingsService.php +++ b/src/mailings/MailingsService.php @@ -1534,4 +1534,19 @@ public function cms2SetTemplate($mailingId, $templatePath) ); return $this->put('mailings/' . $mailingId . '/cms2/contents', '', $queryParameters); } + + /** + * Returns the mailing thumbnail as a byte array. + * + * @param integer $mailingId + * the ID of the mailing + * @return MaileonAPIResult + * the result object of the API call + * @throws MaileonAPIException + * if there was a connection problem or a server error occurred + */ + public function cms2GetThumbnail($mailingId) + { + return $this->get('mailings/' . $mailingId . '/cms2/contents/thumbnail', [], "application/json"); + } } diff --git a/version.txt b/version.txt index c22e205..11654ad 100644 --- a/version.txt +++ b/version.txt @@ -1,2 +1,2 @@ -dist.version = 1.9.7 -dist.version.stable = 1.9.7 +dist.version = 1.9.8 +dist.version.stable = 1.9.8 From 56f7ba3af6c37e99f09b4fd104d26fa434c86167 Mon Sep 17 00:00:00 2001 From: mbeckerle Date: Tue, 27 Jun 2023 07:17:54 +0200 Subject: [PATCH 2/6] Updating versions --- CHANGELOG | 6 +++++- version.txt | 4 ++-- 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/CHANGELOG b/CHANGELOG index 27d2af9..cec880c 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -1,4 +1,8 @@ -Date 2023-06-30 +Date 2023-06-27 +Version 1.9.9 +- removing utf8_encode function calls deprecated in PHP 8.2 + +Date 2023-06-23 Version 1.9.8 - Added method to retrieve thumbnails of CMS2 mailings diff --git a/version.txt b/version.txt index 11654ad..f8351fc 100644 --- a/version.txt +++ b/version.txt @@ -1,2 +1,2 @@ -dist.version = 1.9.8 -dist.version.stable = 1.9.8 +dist.version = 1.9.9 +dist.version.stable = 1.9.9 From 6ed546ee92e571dd61dc3f3cfcc5688cf73a8052 Mon Sep 17 00:00:00 2001 From: Andreas Lange Date: Wed, 2 Aug 2023 13:13:39 +0200 Subject: [PATCH 3/6] Default Timeout Set a default timout of 5ms in case an integration misses to set this. --- src/AbstractMaileonService.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/AbstractMaileonService.php b/src/AbstractMaileonService.php index f361773..4bbe0e9 100644 --- a/src/AbstractMaileonService.php +++ b/src/AbstractMaileonService.php @@ -71,7 +71,7 @@ abstract class AbstractMaileonService * * @var int $timeout */ - protected $timeout; + protected $timeout = 5; private $verboseOut = null; From 37166d0325e2b812892e6ad811ebcee8cc337b43 Mon Sep 17 00:00:00 2001 From: Andreas Lange Date: Mon, 4 Mar 2024 10:57:47 +0100 Subject: [PATCH 4/6] Update README --- README.md | 461 ++++++++++++++++++++++++++---------------------------- 1 file changed, 225 insertions(+), 236 deletions(-) diff --git a/README.md b/README.md index 0588d67..6f322db 100644 --- a/README.md +++ b/README.md @@ -80,280 +80,268 @@ Manage automatic data distributions to notify external systems of specific event ### Contact examples * Request basic **contact data** identified by their email address: - ```php - 'Your API key', - ]); +$contactsService = new ContactsService([ + 'API_KEY' => 'Your API key', +]); - $contact = $contactsService->getContactByEmail('foo@bar.com')->getResult(); +$contact = $contactsService->getContactByEmail('foo@bar.com')->getResult(); - /** - * The contact object stores all information you requested. - * - * Identifiers (Maileon ID, Maileon external id and email address), marketing permission - * level, creation date and last update date are always included if they are set in Maileon. - * - * ID: $contact->id - * Email: $contact->email - * Permission: $contact->permission->getType() - */ - ``` +/** +* The contact object stores all information you requested. +* +* Identifiers (Maileon ID, Maileon external id and email address), marketing permission +* level, creation date and last update date are always included if they are set in Maileon. +* +* ID: $contact->id +* Email: $contact->email +* Permission: $contact->permission->getType() +*/ +``` -* Request a contact identified by it's email address including their **first name and a predefined custom field** and also check for a valid response: - ```php - 'Your API key', +]); + +$getContact = $contactsService->getContactByEmail( + email:'foo@bar.com', + standard_fields:[ + StandardContactField::$FIRSTNAME, + StandardContactField::$LASTNAME, + ], + custom_fields:[ + 'My custom field in Maileon', + ] +); + +if (!$getContact->isSuccess()) { + die($getContact->getResultXML()->message); +} + +$contact = $getContact->getResult(); + +/** + * The contact object stores all information you requested. + * + * Identifiers (Maileon ID, Maileon external id and email address), marketing permission + * level, creation date and last update date are always included if they are set in Maileon. + * + * ID: $contact->id + * Email: $contact->email + * Permission: $contact->permission->getType() + * First name: $contact->standard_fields[StandardContactField::$FIRSTNAME]; + * Custom field: $contact->custom_fields['My custom field in Maileon']; + */ +``` - use de\xqueue\maileon\api\client\contacts\ContactsService; - use de\xqueue\maileon\api\client\contacts\StandardContactField; +* Create a contact in Maileon +```php + 'Your API key', +]); + +$contact = new Contact( + email:'foo@bar.com', + standard_fields:[ + StandardContactField::$FIRSTNAME => 'Foo', + StandardContactField::$LASTNAME => 'Bar', + ], + custom_fields:[ + 'My custom field in Maileon' => 'A value corresponding to the field type', + ], +); + +$contactsService->createContact( + contact:$contact, + syncMode:SynchronizationMode::$IGNORE, + src:'An optional source of the contact creation', + subscriptionPage:'An additional source of the contact creation', + doi:true, + doiPlus:true, // Enable single user tracking with the DOI process + doiMailingKey:'A key to identify the DOI mailing', +); +``` - require __DIR__ . '/vendor/autoload.php'; +* Synchronize a larger list of contacts in bulk +```php + 'Your API key', - ]); +use de\xqueue\maileon\api\client\contacts\ContactsService; +use de\xqueue\maileon\api\client\contacts\Contacts; +use de\xqueue\maileon\api\client\contacts\Contact; +use de\xqueue\maileon\api\client\contacts\Permission; +use de\xqueue\maileon\api\client\contacts\SynchronizationMode; +use de\xqueue\maileon\api\client\contacts\StandardContactField; - $getContact = $contactsService->getContactByEmail( - email:'foo@bar.com', - standard_fields:[StandardContactField::$FIRSTNAME], - custom_fields:['My custom field in Maileon'] - ); +require __DIR__ . '/vendor/autoload.php'; - if (!$getContact->isSuccess()) { - die($getContact->getResultXML()->message); - } - - $contact = $getContact->getResult(); - - /** - * The contact object stores all information you requested. - * - * Identifiers (Maileon ID, Maileon external id and email address), marketing permission - * level, creation date and last update date are always included if they are set in Maileon. - * - * ID: $contact->id - * Email: $contact->email - * Permission: $contact->permission->getType() - * First name: $contact->standard_fields[StandardContactField::$FIRSTNAME]; - * Custom field: $contact->custom_fields['My custom field in Maileon']; - */ - ``` - -* **Create** a contact in Maileon - ```php - 'Your API key', - 'DEBUG'=> true // Remove on production config! - ]); - - // Create the contact object - $newContact = new Contact(); - $newContact->email = "max.mustermann@xqueue.com"; - $newContact->permission = Permission::$NONE; // The initial permission of the newly created contact. This ccan be converted to DOI after DOI process or can be set to something else, e.g. SOI, here already - - // If required, fill custom fields - $newContact->standard_fields[StandardContactField::$FIRSTNAME] = "Max"; - $newContact->standard_fields[StandardContactField::$LASTNAME] = "Mustermann"; - - // Also customfields are available - //$newContact->custom_fields["type"] = "b2c"; - - // And a list of contact preferences can also be added - //$newContact->preferences = array( - // new Preference('EmailSegment1', null, 'Email', 'true'), - // new Preference('EmailSegment2', null, 'Email', 'true') - //); - - // Configuration of behavior or additional data - $src = ""; // a free to be chosen key for the source of the subscription - $subscriptionPage = ""; // a free to be chosen key to identify the subscription page - $doi = true; // true = a DOI mailing will be issued, this will cause an error, if no DOI mail is active in the newsletter account - $doiplus = true; // true = DOI + agreement for single user tracking is enabled, so clicks and opens are not anonymously logged - $doimailingkey = ""; // if several DOI mailings are enabled, this key decides which DOI to trigger - - $response = $contactsService->createContact($newContact, SynchronizationMode::$UPDATE, $src, $subscriptionPage, $doi, $doiplus, $doimailingkey); - ``` - -* **Synchronize** a larger list of contacts with Maileon - ```php - 'Your API key', - 'DEBUG'=> true // Remove on production config! - ]); - - // Some setup variables, see https://maileon.com/support/synchronize-contacts/ - $useExternalId = false; - $ignoreInvalidContacts = true; - $reimportUnsubscribedContacts = true; - $overridePermission = false; - $updateOnly = false; - - // Creating 10.000 dummy contacts - $contactsToSyncTmp = new Contacts(); - for ($i=0; $i<10000; $i++) { - $contactsToSyncTmp->addContact( - new Contact( - null, - 'max_'.$i.'.mustermann@baunzt.de', - null, - 'external-id-'.$i, - $anonymous = null, - array( - StandardContactField::$LASTNAME => 'Mustermann', - StandardContactField::$FIRSTNAME => 'Max_'.$i - ),array( - 'my_customfield_1' => 'value_'.$i, - 'my_customfield_2' => 'another_value_'.$i - ) - } +$contactsService = new ContactsService([ + 'API_KEY' => 'Your API key', +]); - $response = $contactsService->synchronizeContacts( - $contactsToSyncTmp, - Permission::$NONE, - SynchronizationMode::$UPDATE, - $useExternalId, - $ignoreInvalidContacts, - $reimportUnsubscribedContacts, - $overridePermission, - $updateOnly); +$contactList = new Contacts(); - // The response contains some statistics and, if ignore_invalid_contatcs is set to true, information about possibly failed contact creations, see https://maileon.com/support/synchronize-contacts/#articleTOC_3 - - ``` +for ($i=1; $i<=10000; $i++) { + $contactList->addContact( + new Contact( + email:"foo-{$i}@bar.com", + standard_fields:[ + StandardContactField::$FIRSTNAME => 'Foo', + StandardContactField::$LASTNAME => 'Bar', + ], + custom_fields:[ + 'My custom field in Maileon' => 'A value corresponding to the field type', + ], + ) + ); +} + +$response = $contactsService->synchronizeContacts( + contacts:$contactList, + syncMode:SynchronizationMode::$IGNORE, + useExternalId:false, + ignoreInvalidContacts:true, + reimportUnsubscribedContacts:false, + overridePermission:false, + updateOnly:false, +); + +// The response contains some statistics and, if ignore_invalid_contacts is set +// to true, information about possibly failed contact creations, see +// https://maileon.com/support/synchronize-contacts/#articleTOC_3 +``` ### Report example * Print all unsubscriptions: - ```php - 'Your API key', - ]); +$contactsService = new ReportsService([ + 'API_KEY' => 'Your API key', +]); - $index = 1; - do { - $getUnsubscribers = $reportsService->getUnsubscribers( - pageIndex:$index++, - pageSize:1000 +$index = 1; +do { + $getUnsubscribers = $contactsService->getUnsubscribers( + pageIndex:$index++, + pageSize:1000 + ); + + foreach ($getUnsubscribers->getResult() as $unsubscriber) { + printf('%s unsusbcribed in mailing %u at %s'.PHP_EOL, + $unsubscriber->contact->email, + $unsubscriber->mailingId, + $unsubscriber->timestamp ); - - foreach ($getUnsubscribers->getResult() as $unsubscriber) { - printf('%s unsusbcribed in mailing %u at %s'.PHP_EOL, - $unsubscriber->contact->email, - $unsubscriber->mailingId, - $unsubscriber->timestamp - ); - } - } while($getUnsubscribers->getResponseHeaders()['X-Pages'] >= $index); - ``` + } +} while($getUnsubscribers->getResponseHeaders()['X-Pages'] >= $index); +``` * Get [KPI](https://kpi.org/KPI-Basics) data for a specific mailing: - ```php - 'Your API key', - ]); +$reportsService = new ReportsService([ + 'API_KEY' => 'Your API key', +]); - $mailingId = 123; +$mailingId = 123; - $recipients = $reportsService->getRecipientsCount(mailingIds:[$mailingId])->getResult(); - $opens = $reportsService->getOpensCount(mailingIds:[$mailingId])->getResult(); - $clicks = $reportsService->getClicksCount(mailingIds:[$mailingId])->getResult(); - $unsubscribers = $reportsService->getUnsubscribersCount(mailingIds:[$mailingId])->getResult(); - $conversions = $reportsService->getConversionsCount(mailingIds:[$mailingId])->getResult(); - ``` +$recipients = $reportsService->getRecipientsCount(mailingIds:[$mailingId])->getResult(); +$opens = $reportsService->getOpensCount(mailingIds:[$mailingId])->getResult(); +$clicks = $reportsService->getClicksCount(mailingIds:[$mailingId])->getResult(); +$unsubscribers = $reportsService->getUnsubscribersCount(mailingIds:[$mailingId])->getResult(); +$conversions = $reportsService->getConversionsCount(mailingIds:[$mailingId])->getResult(); +``` ### Mailing example * Create a new mailing, add custom HTML content, attach a target group and send it immediately: - ```php - 'Your API key', - ]); - - $mailingId = $mailingsService->createMailing( - name:'My campaign name', - subject:'Hi [CONTACT|FIRSTNAME]! We got some news for you!' - )->getResult(); - - $mailingsService->setSender($mailingId, 'foo@bar.com'); - $mailingsService->setSenderAlias($mailingId, 'Maileon news team'); - $mailingsService->setHTMLContent( - mailingId:$mailingId, - html:'...', - doImageGrabbing:true, - doLinkTracking:true - ); - $mailingsService->setTargetGroupId($mailingId, 123); - $mailingsService->sendMailingNow($mailingId); - ``` +```php + 'Your API key', +]); + +$mailingId = $mailingsService->createMailing( + name:'My campaign name', + subject:'Hi [CONTACT|FIRSTNAME]! We got some news for you!' +)->getResult(); + +$mailingsService->setSender($mailingId, 'foo@bar.com'); +$mailingsService->setSenderAlias($mailingId, 'Maileon news team'); +$mailingsService->setHTMLContent( + mailingId:$mailingId, + html:'...', + doImageGrabbing:true, + doLinkTracking:true +); +$mailingsService->setTargetGroupId($mailingId, 123); +$mailingsService->sendMailingNow($mailingId); +``` ### Transaction example * Send a new transaction including product information as an order confirmation: - ```php - 'Your API key', - ]); +$transactionsService = new TransactionsService([ + 'API_KEY' => 'Your API key', +]); - $transaction = new Transaction(); - $transaction->typeName = 'My event to trigger'; - - $transaction->contact = new ContactReference([ - 'email' => 'foo@bar.com' - ]); - - $transaction->content = [ +$transaction = new Transaction( + typeName:'My event to trigger', + contact:new ContactReference( + email:'foo@bar.com' + ), + content:[ 'foo' => 'bar', 'items' => [ [ @@ -367,7 +355,8 @@ Manage automatic data distributions to notify external systems of specific event 'price' => 16.49 ], ], - ]; + ] +); - $transactionsService->createTransactions([$transaction]); - ``` +$transactionsService->createTransactions([$transaction]); +``` From 3456770b61f8e06e405252bf32cae6a5ed3b22a5 Mon Sep 17 00:00:00 2001 From: Andreas Lange Date: Mon, 4 Mar 2024 10:58:51 +0100 Subject: [PATCH 5/6] Update README --- README.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 6f322db..7fe793e 100644 --- a/README.md +++ b/README.md @@ -177,7 +177,7 @@ $contact = new Contact( ], ); -$contactsService->createContact( +$creation = $contactsService->createContact( contact:$contact, syncMode:SynchronizationMode::$IGNORE, src:'An optional source of the contact creation', @@ -186,6 +186,10 @@ $contactsService->createContact( doiPlus:true, // Enable single user tracking with the DOI process doiMailingKey:'A key to identify the DOI mailing', ); + +if (!$contact->isSuccess()) { + die($contact->getResultXML()->message); +} ``` * Synchronize a larger list of contacts in bulk From 58959ade8588b8a8a04b91d144456aadba19ea7b Mon Sep 17 00:00:00 2001 From: Andreas Lange Date: Mon, 4 Mar 2024 10:59:37 +0100 Subject: [PATCH 6/6] Update README --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 7fe793e..6f9b501 100644 --- a/README.md +++ b/README.md @@ -187,8 +187,8 @@ $creation = $contactsService->createContact( doiMailingKey:'A key to identify the DOI mailing', ); -if (!$contact->isSuccess()) { - die($contact->getResultXML()->message); +if (!$creation->isSuccess()) { + die($creation->getResultXML()->message); } ```