unione/unione-php

The UniOne SDK package what provide methods to interact with UniOne API.


README

Latest Stable Version Total Downloads

This SDK contains methods for easily interacting with the UniOne API: https://docs.unione.io/en/web-api-ref#web-api

Installation

Use Composer to install the package:

composer require unione/unione-php

Usage

Send email:

  $client = new Unione\UnioneClient('YOUR-API-KEY', 'YOUR-HOST-NAME');
  // Example for EU instance.
  $client = new Unione\UnioneClient('YOUR-API-KEY', 'eu1.unione.io');

  $recipients = [
    [
      "email" => 'john@example.com',
      "substitutions" => [
        "to_name" => "John Smith"
      ],
    ],
    [
      "email" => 'liza@example.com',
      "substitutions" => [
        "to_name" => "Liza Frank"
      ],
    ]
  ];

  $body = [
    "html" => "<b>Test mail, {{to_name}}</b>",
    "plaintext" => "Hello, {{to_name}}",
    "amp" => "<!doctype html><html amp4email><head> <meta charset=\"utf-8\"><script async src=\"https://cdn.ampproject.org/v0.js\"></script> <style amp4email-boilerplate>body[visibility:hidden]</style></head><body> Hello, AMP4EMAIL world.</body></html>"
  ];

  // You can use email object can be used to prepare the message array.
  // But the email send method accepts an array, that can be composed without
  // SDK utils.
  $mail = new Unione\Model\Email($recipients, $body);
  $mail->setFromEmail('user@example.com');
  $mail->setSubject('test letter');
  $response = $client->emails()->send($mail->toArray());

See API documentation for more details.

See template engine documentation for substitutions details.

Send subscribe email:

  $client = new Unione\UnioneClient('YOUR-API-KEY', 'YOUR-HOST-NAME');

  $params = [
    "from_email" => "john@example.com",
    "from_name" => "John Smith",
    "to_email" => "user@example.com"
  ];
  $response = $client->emails()->subscribe($params);

API documentation.

Set template:

  $client = new Unione\UnioneClient('YOUR-API-KEY', 'YOUR-HOST-NAME');

  $params = [
    "template" => [
      "name" => "First template",
      "body" => [
        "html" => "<b>Hello, {{to_name}}</b>",
        "plaintext" => "Hello, {{to_name}}",
        "amp" => "<!doctype html><html amp4email><head> <meta charset=\"utf-8\"><script async src=\"https://cdn.ampproject.org/v0.js\"></script> <style amp4email-boilerplate>body[visibility:hidden]</style></head><body> Hello, AMP4EMAIL world.</body></html>"
      ],
      "subject" => "Test template mail",
      "from_email" => "test@example.com",
      "from_name" => "Example From",
    ]
  ];
  $response = $client->templates()->set($params);

API documentation.

Get template:

  $client = new Unione\UnioneClient('YOUR-API-KEY', 'YOUR-HOST-NAME');
  $response = $client->templates()->get('YOUR-TEMPLATE-ID');

API documentation.

Get templates list:

  $client = new Unione\UnioneClient('YOUR-API-KEY', 'YOUR-HOST-NAME');

  $params = [
    "limit" => 50,
    "offset" => 0
  ];
  $response = $client->templates()->list($params);

API documentation.

Delete template:

  $client = new Unione\UnioneClient('YOUR-API-KEY', 'YOUR-HOST-NAME');
  $response = $client->templates()->delete('YOUR-TEMPLATE-ID');

API documentation.

Set webhook:

  $client = new Unione\UnioneClient('YOUR-API-KEY', 'YOUR-HOST-NAME');

  $params = [
    "url" => "https://yourhost.example.com/unione-webhook",
    "events" => [
      "email_status" => [
        "delivered",
        "opened",
        "clicked",
        "unsubscribed",
        "soft_bounced",
        "hard_bounced",
        "spam"
      ]
    ]
  ];
  $response = $client->webhooks()->set($params);

API documentation.

The specified URL will receive a request from Unione. See more information about request data in API documentation.

This is how you can check the message integrity in your callback handler:

$client = new Unione\UnioneClient('YOUR-API-KEY', 'YOUR-HOST-NAME');
// $body contains a callback request body.
if ($client->webhooks()->verify($body) === TRUE) {
  // The webhook is confirmed, result can be processed.
}

Get webhook:

  $client = new Unione\UnioneClient('YOUR-API-KEY', 'YOUR-HOST-NAME');
  $response = $client->webhooks()->get('YOUR-WEBHOOK-URL');

API documentation.

Get list all or some webhooks:

  $client = new Unione\UnioneClient('YOUR-API-KEY', 'YOUR-HOST-NAME');
  $response = $client->webhooks()->list();

API documentation.

Delete webhook:

  $client = new Unione\UnioneClient('YOUR-API-KEY', 'YOUR-HOST-NAME');
  $response = $client->webhooks()->delete('YOUR-WEBHOOK-URL');

API documentation.

Additional information

Generic API method

For API methods, that are not implemented in SDK yet, you can use UnioneClient::httpRequest(). Here is an example for "set" suppression method:

  $client = new Unione\UnioneClient('YOUR-API-KEY', 'YOUR-HOST-NAME');
  $response = $client->httpRequest('suppression/set.json', ["email" => "user@example.com", "cause" => "unsubscribed"]);

Set Guzzle HTTP client config

Unione client accepts an array with Guzzle configuration as a third argument. When creating a client, you can pass some additional options (i.e. connect_timeout) to apply this to all requests.

Here is a more advanced example of adding a history handler to save outcoming requests and responses.

  $container = [];
  $history = Middleware::history($container);
  $handlerStack = HandlerStack::create();
  $handlerStack->push($history);
  $config = ['handler' => $handlerStack];
  $client = new Unione\UnioneClient('YOUR-API-KEY', 'YOUR-HOST-NAME', $config);

See Guzzle documentation.