mailingreport / mailingreport-php
Official MailingReport library for PHP
Requires
- php: >=5.3.0
- doctrine/inflector: ~1.0
- guzzle/guzzle: ~3.7
Requires (Dev)
- phpunit/phpunit: ~3.7
README
The official PHP client for the MailingReport API. For more information, documentation, integration, plugins, ... about MailingReport API, please visit the developers dedicated website: https://fr.mailingreport.com/api/
Installation
The recommended way to install MailingReport API is through composer:
{ "require": { "mailingreport/mailingreport-php": "@stable" } }
Usage
Create an api client
You can find these credentials in your MailingReport account inside the "Settings" section then "Api keys".
$api = \Mgrt\Client::factory(array( 'public_key' => 'your_public_key', 'private_key' => 'your_private_key', ));
Here is a complete list of settings available. See also Guzzle's manual for more options.
public_key
: Your API keyprivate_key
: Your API secret
Retrieving collection
When retrieving a collection you will get a ResultCollection
class. You can get the current page, the limit and the total number of elements in the global collection.
$contacts = $api->getContacts(); $contacts->getPage(); // 1 $contacts->getLimit(); // 50 $contacts->getTotal(); // 250 for example
You can also set parameters when retrieving a collection.
$contacts = $contacts->getContacts(array( 'page' => 2, 'limit' => 10, 'sort' => 'createdAt', 'direction' => 'asc', )); $contacts->getPage(); // 2 $contacts->getLimit(); // 10 $contacts->getTotal(); // 250 for example
With the ResultCollection you can iterate over the collection.
foreach ($contacts as $contact) { echo $contact->getId(); // 1 for example }
Creating entries
You can create a new object by using the default constructor and setting the fields one by one.
$custom_field = new \Mgrt\Model\CustomField(); $custom_field ->setId(42); ->setValue('the answer to life the universe and everything'); $contact = new \Mgrt\Model\Contact(); $contact ->setEmail('somebody@example.com'); ->setCustomFields(array( $custom_field ));
or you can use php array structure to define new objects
$contact = new \Mgrt\Model\Contact(); $contact->fromArray(array( 'email' => 'somebody@example.com', 'custom_fields' => array( 'id' => 42, 'value' => 'the answer to life the universe and everything' ) ));
Accounts
Available API methods
$api->getAccount()
will return aAccount
object.
Available methods on Account
object
$account->getId()
will return aninteger
.$account->getCompany()
will return astring
.$account->getAddressStreet()
will return astring
.$account->getAddressCity()
will return astring
.$account->getAddressZipcode()
will return astring
.$account->getAddressCountry()
will return astring
.$account->getCurrency()
will return astring
.$account->getTimezone()
will return astring
.$account->getCredits()
will return ainteger
.$account->getPlanType()
will return astring
.
ApiKeys
Available API methods
$api->getApiKeys()
will return aResultCollection
containing a collection ofApiKey
.$api->getApiKey($apiKeyId)
will return aApiKey
object.$api->createApiKey(ApiKey $apiKey)
will return aApiKey
object.$api->updateApiKey(ApiKey $apiKey)
will return aboolean
.$api->deleteApiKey(ApiKey $apiKey)
will return aboolean
.$api->disableApiKey(ApiKey $apiKey)
will return aboolean
.$api->enableApiKey(ApiKey $apiKey)
will return aboolean
.
Available methods on ApiKeys
object
Getters
$apiKey->getId()
will return aninteger
.$apiKey->getName()
will return astring
.$apiKey->getPublicKey()
will return astring
.$apiKey->getPrivateKey()
will return astring
.$apiKey->getEnabled()
will return aboolean
.$apiKey->getCreatedAt()
will return aDateTime
.$apiKey->getDisabledAt()
will return aDateTime
.
Setters
$apiKey->setName($name)
where$name
is astring
.
Campaigns
Available API methods
$api->getCampaigns()
will return aResultCollection
containing a collection ofCampaign
.$api->getCampaign($contactId)
will return aCampaign
object.$api->createCampaign(Campaign $campaign)
will return aCampaign
object.$api->updateCampaign(Campaign $campaign)
will return aboolean
.$api->deleteCampaign(Campaign $campaign)
will return aboolean
.$api->scheduleCampaign(Campaign $campaign)
will return aboolean
.$api->unscheduleCampaign(Campaign $campaign)
will return aboolean
.$api->summaryCampaign(Campaign $campaign)
will return aCampaignSummary
object.
Available methods on Campaign
object
Getters
$campaign->getId()
will return aninteger
.$campaign->getName()
will return astring
.$campaign->getMailingLists()
will return an array ofMailingList
objects.$campaign->getSegments()
will return an array ofSegment
objects.$campaign->getSubject()
will return astring
.$campaign->getBody()
will return astring
.$campaign->getFromMail()
will return astring
.$campaign->getFromName()
will return astring
.$campaign->getReplyMail()
will return astring
.$campaign->getCreatedAt()
will return aDateTime
.$campaign->getUpdatedAt()
will return aDateTime
.$campaign->getScheduledAt()
will return aDateTime
.$campaign->getSentAt()
will return aDateTime
.$campaign->getTrackingEndsAt()
will return aDateTime
.$campaign->getStatus()
will return astring
.$campaign->getIsPublic()
will return aboolean
.$campaign->getShareUrl()
will return astring
.
Setters
$campaign->setName($name)
where$name
is astring
.$campaign->setMailingLists($mailingLists)
where$mailingLists
is an array ofMailingLists
objects.$campaign->setSegments($segments)
where$segments
is an array ofSegments
objects.$campaign->setSubject($subject)
where$subject
is astring
.$campaign->setBody($body)
where$body
is astring
.$campaign->setFromMail($fromMail)
where$fromMail
is astring
.$campaign->setFromName($fromName)
where$fromName
is astring
.$campaign->setReplyMail($replyMail)
where$replyMail
is astring
.
Contacts
Available API methods
$api->getContacts()
will return aResultCollection
containing a collection ofContact
.$api->getContact($contactId)
will return aContact
object.$api->getContact($contactEmail)
will return aContact
object.$api->createContact(Contact $contact)
will return aContact
object.$api->updateContact(Contact $contact)
will return aboolean
.$api->deleteContact(Contact $contact)
will return aboolean
.$api->unsubscribeContact(Contact $contact)
will return aboolean
.$api->resubscribeContact(Contact $contact)
will return aboolean
.
Available methods on Contact
object
Getters
$contact->getId()
will return aninteger
.$contact->getEmail()
will return astring
.$contact->getMailingLists()
will return an array ofMailingList
objects.$contact->getMailingListsToArray()
will return an array ofinteger
.$contact->getCustomFields()
will return an array ofCustomField
objects.$contact->getCustomFieldsToArray()
will return an array of CustomFields, formatted as an array of {id, value}.$contact->getLatitude()
will return astring
.$contact->getLongitude()
will return astring
.$contact->getCountryCode()
will return astring
.$contact->getTimeZone()
will return astring
.$contact->getCreatedAt()
will return aDateTime
.$contact->getUpdatedAt()
will return aDateTime
.
Setters
$contact->setEmail($email)
where$email
is astring
.$contact->setMailingLists($mailingList)
where$mailingList
is an array ofMailingList
objects.$contact->setCustomFields($customFields)
where$customFields
is an array ofCustomField
objects.
Other methods
$contact->addMailingLists($mailingList)
where$mailingList
is an array ofMailingList
objects.$contact->removeMailingLists($mailingList)
where$mailingList
is an array ofMailingList
objects.$contact->addMailingList($mailingList)
where$mailingList
is aMailingList
object.$contact->removeMailingList($mailingList)
where$mailingList
is aMailingList
object.$contact->addCustomFields($customFields)
where$customFields
is an array ofCustomField
objects.$contact->removeCustomFields($customFields)
where$customFields
is an array ofCustomField
objects.$contact->addCustomField($customFields)
where$customFields
is aCustomField
object.$contact->removeCustomField($customFields)
where$customFields
is aCustomField
object.
Custom Fields
Custom fields cannot be created or updated from the API
Available API methods
$api->getCustomFields()
will return aResultCollection
containing a collection ofCustomField
.
Available methods on CustomField
object
$customField->getId()
will return aninteger
.$customField->getName()
will return astring
.$customField->getFieldType()
will return astring
.$customField->getValue()
will return astring
.$customField->getChoices()
will return an array ofstring
.
Domains
Domains cannot be created or updated from the API
Available API methods
$api->getDomains()
will return aResultCollection
containing a collection ofDomain
.$api->getDomain($domainId)
will return aDomain
object.$api->checkDomain(Domain $domain)
will return aDomain
object.
Available methods on Domain
object
$domain->getId()
will return aninteger
.$domain->getDomainName()
will return astring
.$domain->getCheckedAt()
will return aDateTime
.$domain->getSpfFqdn()
will return astring
.$domain->getSpfStatus()
will return aninteger
.$domain->getDkimFqdn()
will return astring
.$domain->getDkimStatus()
will return aninteger
.$domain->getPublicKey()
will return astring
.
Invoices
Invoices cannot be created or updated from the API
Available API methods
$api->getInvoices()
will return aResultCollection
containing a collection ofInvoice
.$api->getInvoice($invoiceId)
will return aInvoice
object.
Available methods on Invoice
object
$invoice->getId()
will return aninteger
.$invoice->getNumber()
will return astring
.$invoice->getNetAmount()
will return afloat
.$invoice->getTaxAmount()
will return afloat
.$invoice->getTotalAmount()
will return afloat
.$invoice->getDueAt()
will return aDateTime
.$invoice->getPaidAt()
will return aDateTime
.$invoice->getInvoiceLines()
will return an array ofInvoiceLine
objects.
Available methods on InvoiceLine
object
$invoiceLine->getId()
will return aninteger
.$invoiceLine->getTitle()
will return astring
.$invoiceLine->getDescription()
will return astring
.$invoiceLine->getQuantity()
will return afloat
.$invoiceLine->getPrice()
will return afloat
.
MailingLists
Available API methods
$api->getMailingLists()
will return aResultCollection
containing a collection ofMailingList
.$api->getMailingList($mailingListId)
will return aMailingList
object.$api->createMailingList(MailingList $mailingList)
will return aMailingList
object.$api->updateMailingList(MailingList $mailingList)
will return aboolean
.$api->deleteMailingList(MailingList $mailingList)
will return aboolean
.$api->getMailingListContacts(MailingList $mailingList)
will return aResultCollection
containing a collection ofContact
.
Available methods on MailingList
object
Getters
$mailingList->getId()
will return aninteger
.$mailingList->getName()
will return astring
.$mailingList->getCreatedAt()
will return aDateTime
.$mailingList->getUpdatedAt()
will return aDateTime
.
Setters
$mailingList->setName($name)
where$name
is astring
.
Senders
Senders cannot be created or updated from the API
Available API methods
$api->getSenders()
will return aResultCollection
containing a collection ofSender
.$api->getSender($senderId)
will return aSender
object.$api->deleteSender(Sender $sender)
will return aboolean
.
Available methods on Sender
object
$sender->getId()
will return aninteger
.$sender->getEmail()
will return astring
.$sender->getEmailType()
will return astring
.$sender->getIsEnabled()
will return aboolean
.
Templates
Available API methods
$api->getTemplates()
will return aResultCollection
containing a collection ofTemplate
.$api->getTemplate($templateId)
will return aTemplate
object.$api->createTemplate(Template $template)
will return aTemplate
object.$api->deleteTemplate(Template $template)
will return aboolean
.$api->updateTemplate(Template $template)
will return aboolean
.
Available methods on Template
object
Getters
$template->getId()
will return aninteger
.$template->getName()
will return astring
.$template->getBody()
will return aDateTime
.
Setters
$campaign->setName($name)
where$name
is astring
.$template->setBody($body)
where$body
is astring
.
Unit Tests
To run unit tests, you'll need a set of dependencies you can install using Composer
Once installed, just launch the following command:
phpunit
Rename the phpunit.xml.dist file to phpunit.xml, then uncomment the following lines and add your own API keys:
<php> <!-- <server name="PUBLIC_KEY" value="your_public_key" /> --> <!-- <server name="PRIVATE_KEY" value="your_private_key" /> --> </php>
You're done.
More informations
Credits
Many thanks to all contributors.
License
This software is released under the MIT License. See the bundled LICENSE file for details.