Mailfire PHP SDK
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
mailfire
tests
.gitignore
README.md
autoloader.php
composer.json
example.php
test.sh

README.md

Mailfire PHP SDK

Latest Stable Version Total Downloads

PHP SDK for https://mailfire.io

Installing

via Composer https://getcomposer.org/download

composer require mailfire/php-sdk

or download lib & include files in dir:

require_once 'autoloader.php';

Quick start: sending email

$clientId = 123;
$clientHash = 'a1s2d3f4g5h6j7k8l';

// Init main object with access credentials
$mf = new Mailfire($clientId, $clientHash);

// You can enable Exceptions for sdk fails
// $mf->errorHandler->setErrorMode(MailfireErrorHandler::MODE_EXCEPTION);

// Required params for letter
$typeId = 1; // letter id (aka type_id)
$categoryId = $mf->push->getCategorySystem(); // system or trigger
$projectId = 1; // in your admin panel
$email = 'test@example.com'; // for matching user

// Variables for letter
$data = [ // Data for letter
    'some' => 'hi',
    'letter' => 'John',
    'variables' => '!',
];

// User info, that will be saved [not required]
$user = [
    'name' => 'John',
    'age' => '22',
    'gender' => 'm',
    'language' => 'en',
    'country' => 'US',
    'platform_id' => $mf->user->getPlatformDesktop(),
    'vip' => 0,
    'photo' => 'http://example.com/somephotourl.jpg',
    'channel_id' => 42,
    'subchannel_id' => 298,
    'client_user_id' => '123xyz'
];
// Your data, that will be sent with our webhooks
$meta = [
    'tracking_id' => 72348234,
];

// Sending
$response = $mf->push->send($typeId, $categoryId, $projectId, $email, $user, $data, $meta);
// it will make POST to /push/system or /push/trigger with json http://pastebin.com/raw/Dy3VeZpB

var_dump($response);
// 

Other API methods

Check email

// Make POST /email/check with json {"email":"Test@Example.com"}
$result = $mf->email->check('Test@Example.com');
/* Returned array(
  'orig' => 'Test@Example.com',
  'valid' => false, // result
  'reason' => 'mx_record', // reason of result
  'email' => 'test@example.com', // fixed email
  'vendor' => 'Unknown', // vendor name like Gmail
  'domain' => 'example.com',
  'trusted' => false,
) */

Validate email


$projectId = 1;
$email = 'test@example.com';
$typeId = 1;

$result = $mf->email->validate($projectId, $email, $typeId);
/* Returned array(
  'code' => ...,
  'text' => ...,
) */

CODES:

EMAIL_VALIDATION_STATUS_PASSED = 1;
EMAIL_VALIDATION_STATUS_INVALID = 2;
EMAIL_VALIDATION_STATUS_SERVER_ERROR = 3;

User info

$projectId = 1;
// Make GET to /user/project/PROJECT_ID/email/Test@Example.com
$user = $mf->user->getByEmail('Test@Example.com', $projectId);
/* Returned array(
    "id":8424,
    "project_id":1,
    "email":"test@example.com",
    "name":"John",
    "gender":"m",
    "country":"UKR",
    "language":"en",
    "last_online":"2016-06-17 12:59:19",
    "last_reaction":"2016-06-17 12:59:19",
    "last_mailed":"2016-06-22 12:06:45",
    "last_request":"2016-06-03 04:01:19",
    "activation":"2016-01-30 11:28:24",
    ...
) */

Unsubscribe

$projectId = 1;
$user = $mf->user->getByEmail('test@example.com', $projectId);
// Make POST to /unsub/USER_ID/source/9
$unsub = $mf->unsub->addBySettings($user);
var_dump($unsub);

Subscribe back

$projectId = 1;
$user = $mf->user->getByEmail('test@example.com', $projectId);
// Make DELETE to /unsub/USER_ID
$unsub = $mf->unsub->subscribe($user);
var_dump($unsub);

Unsubscribe from types

$projectId = 1;
$user = $mf->user->getByEmail('test@example.com', $projectId);
$list = $mf->unsubTypes->getList($user);
var_dump($list);
//array(2) {
//  [0] =>
//  array(3) {
//    'type_id' =>
//   int(3)
//    'unsubscribed' =>
//    bool(false)
//    'name' =>
//    string(11) "Popular now"
//  }
//  [1] =>
//  array(3) {
//    'type_id' =>
//    int(4)
//    'unsubscribed' =>
//    bool(false)
//    'name' =>
//    string(8) "Breaking"
//  }
//}

$result = $mf->unsubTypes->setDisabledTypes(12, [4]); //subscribes
//for all active type_id`s except 4

$mf->unsubTypes->addTypes(12, [4]); //unsubscribe user from type 4
$mf->unsubTypes->removeTypes(12, [4]); //subscribe user for type 4
$mf->unsubTypes->removeAll(12); //subscribe user for all types

Unsubscribe by admin

$projectId = 123;
$result = $mf->unsub->unsubByAdmin('test@example.com',$projectId);

/*
success result
array(1) {
  'unsub' => bool(true)
}
error result (already unsubscribed)
array(1) {
  'unsub' => bool(false)
}
*/

Check is unsubscribed

By user:

$projectId = 1;
$user = $mf->user->getByEmail('test@example.com', $projectId);
$unsub = $mf->unsub->isUnsubByUser($user); // Returns false(if not unsubscribed) or unsub data

By email and project:

$projectId = 1;
$unsub = $mf->unsub->isUnsubByEmailAndProjectId('test@example.com', $projectId); // Returns false(if not unsubscribed) or unsub data

Get unsubscribe reason

$projectId = 123;
$result = $mf->unsub->getUnsubscribeReason('test@example.com',$projectId);

//user does not unsubscribed
array(1) {
  'result' => bool(false)
}

//reason for the unsubscription is unknown
array(1) {
  'result' => string(7) "Unknown"
}

//success result
array(1) {
  'result' => string(5) "admin"
}

Get unsubscribed list

<?php

$result = $mf->unsub->getByDate('2018-06-10');

//Response example
return [
    0 => [
        'email' => "jo23lu56@gmail.com",
        'project_id' => 9,
        'client_user_id' => NULL,
        'source_id' => 9,
        'created_at' => "2018-02-27 20:31:45"
    ],
    // ...
];

Send push notification

//select user
$user = $mf->user->getByEmail('someone@example.com', 2);
//webpush data
$title = 'Webpush title';
$text = 'My awesome text';
$url = 'https://myproject.com/show/42';
$iconUrl = 'https://static.myproject.com/6hgf5ewwfoj6';
$typeId = 6;
//send
$mf->webpush->sendByUser($user, $title, $text, $url, $iconUrl, $typeId);

Send push notification to all project users

//webpush data
$projectId = 1;
$title = 'Webpush title';
$text = 'My awesome text';
$url = 'https://myproject.com/show/42';
$iconUrl = 'https://static.myproject.com/6hgf5ewwfoj6';
$typeId = 6;
//send
$mf->webpush->sendByProject($projectId, $title, $text, $url, $iconUrl, $typeId);

Unsubscribe/Subscribe user for push notifications

//select user
$user = $mf->user->getByEmail('someone@example.com', 2);
//unsubscribe
$mf->webpush->unsubscribeByUser($user);
//subscribe back
$mf->webpush->subscribeByUser($user);
//unsubscribe by push user id
$pushUserId = 123;
$mf->webpush->unsubscribeByPushUser($pushUserId);

Create and update user data

$fields = [
    'name' => 'John Dou',
    'gender' => 'm', //m or f
    'age' => 21, //int
    'photo' => 'http://moheban-ahlebeit.com/images/Face-Wallpaper/Face-Wallpaper-26.jpg',//image url
    'ak' => 'FFZxYfCfGgNDvmZRqnELYqU7',//Auth key
    'vip' => 1, //int
    'language' => 'es', //ISO 639-1
    'country' => 'esp', //ISO 3166-1 alpha-3 or ISO 3166-1 alpha-2
    'platform_id' => $mf->user->getPlatformDesktop(),
    'list_id' => 1,
    'status' => 0, //int
    'partner_id' => 1, //int

    // Your own custom fields may be here
    // allowed only int values
    'field1' => 542, //int
    'sessions_count' => 22, //int
    'session_last' => 1498137772, //unix timestamp
];

By email and project ID

$result = $mf->user->setUserFieldsByEmailAndProjectId('ercling@yandex.ru', 2, $fields);
// $result is a boolean status

By user

$user = $mf->user->getById(892396028);
$result = $mf->user->setUserFieldsByUser($user, $fields);
// $result is a boolean status

Payments

$startDate = 1509617696;
$expireDate = 1609617696; //optional
$paymentCount = 14; //optional
$paymentType = 1 // optional

By email and project ID

$result = $mf->user->addPaymentByEmailAndProjectId('ercling@yandex.ru', 2, $startDate, $expireDate, $paymentCount, $paymentType);
// $result is a boolean status

By user

$user = $mf->user->getById(892396028);
$result = $mf->user->addPaymentByUser($user, $startDate, $expireDate, $paymentCount, $paymentType);
// $result is a boolean status

Attempt to send incorrect data

$mf = new \Mailfire(3,'GH3ir1ZDMjRkNzg4MzgzE3MjU');
$fields = [
    'language' => 'ua',
    'gender' => 'male',
    'vip' => 'yes',
];
$result = $mf->user->setUserFieldsByEmailAndProjectId('ercling@yandex.ru', 2, $fields);
if (!$result){
    var_dump($mf->request->getLastResponse()->getData());
}

//array(3) {
//  'errorCode' =>
//  int(409)
//  'message' =>
//  string(16) "Validation error"
//  'errors' =>
//  array(3) {
//    'language' =>
//    string(45) "Field language is not valid language code: ua"
//    'gender' =>
//    string(41) "Field gender must be a part of list: m, f"
//    'vip' =>
//    string(44) "Field vip does not match the required format"
//  }
//}

Update user online

By user

$result = $mf->user->setOnlineByUser($user, new \DateTime()); //Accepted

By email and project ID

$result = $mf->user->setOnlineByEmailAndProjectId('ercling@gmail.com', 1, new \DateTime());

Get user custom fields

By email and project ID

$result = $mf->user->getUserFieldsByEmailAndProjectId('ercling@yandex.ru', 1);
/*
Returns [
    'user' => [
        'id' => 892396028,
        'project_id' => 1,
         ...
    ],
    'custom_fields' => [
        'sessions_count' => 22,
         ...
    ],
]
*/

By user

$user = $mf->user->getById(892396028);
$result = $mf->user->getUserFieldsByUser($user);
/*
Returns [
    'user' => [
        'id' => 892396028,
        'project_id' => 1,
         ...
    ],
    'custom_fields' => [
        'sessions_count' => 22,
         ...
    ],
]
*/

Send goals using sdk

$data = [
    [
        'email' => 'someone@example.com',
        'type' => 'some_type',
        'project_id' => 123,
        'mail_id' => '123123123',
    ],
    [
        'email' => 'someone1@example.com',
        'type' => 'some_type',
        'project_id' => 345,
        'mail_id' => '345345345',
    ]];

$res = $mf->goal->createGoal($data);




Success response

/*
array(1) {
  'goals_added' => int(2)
}
*/

Error response

/*
array(3) {
  'goals_added' =>
  int(0)
  [0] =>
  array(4) {
    'error_messages' =>
    array(1) {
      [0] =>
      string(25) "Parameter type is invalid"
    }
    'errorCode' =>
    int(409)
    'message' =>
    string(16) "Validation error"
    'goal_data' =>
    string(39) "somemail@example.com;<h1>;123;123123123"
  }
  [1] =>
  array(4) {
    'error_messages' =>
    array(1) {
      [0] =>
      string(26) "Parameter email is invalid"
    }
    'errorCode' =>
    int(409)
    'message' =>
    string(16) "Validation error"
    'goal_data' =>
    string(46) "somem@ail1@example.com;some_type;345;345345345"
  }
}
*/

Send goals without sdk

POST https://api.mailfire.io/v1/goals
params: {
            'type' : 'contact',
            'email' : 'andrey.reinwald@corp.flirchi.com', 
            'project_id' : 30,
            'mail_id' : 2739212714|null
        }

Request format

Name Type Description
type string Required. Goal type
email string Required. User email
project_id int Required. Id of your project. You can find it at https://admin.mailfire.io/account/projects
mail_id int Mail id after which the user made a goal

Application pushes

$token - application token from Firebase server

$uid - unique identifier of users device

Send data notification

$message = ['title' => 'Hello'];

$message = jsone_encode($message);

$result = $mf->appPush->send($project, $uid, $message);

Create user

$result = $mf->appPush->createPushUser($project, $token, $uid, $platform, $userId = null);
// $result is id of created user

platform - user platform, Android - 1, IOS - 2

Refresh token

$result = $mf->appPush->refreshToken($project, $token, $uid);
// $result is a boolean status

Track show

$created - show time in timestamp format
$result = $mf->appPush->trackShow($project, $uid, $pushId, $created);
// $result is a boolean status

Track click

$created - click time in timestamp format
$result = $mf->appPush->trackClick($project, $uid, $pushId, $created);
// $result is a boolean status

Update online

$result = $mf->appPush->updateOnline($project, $uid);
// $result is a boolean status

Content

$entityId - ID of entity which user watched

$uid - unique identifier of users device

Track show

$result = $mf->content->trackShow($project, $uid, $entityId = null);
// $result is a boolean status

Force confirm update

$result = $mf->user->forceConfirmByEmailAndProject($email, $projectId);
// $result == 'Accepted'; if successful

Get response (if $result === false)

$response = $mf->request->getLastResponse()->getData();

//array(3) {
//  'errorCode' =>
//  int(409)
//  'message' =>
//  string(16) "Validation error"
//  'errors' =>
//  array(1) {
//    'field_name' =>
//    string(29) "Can't find user field: field2"
//  }
//}

Error handling

By default any error messages (except InvalidArgumentException in Mailfire constructor) collects in error_log. If you want the component throws exceptions just change handler mode:

$mf = new Mailfire($clientId, $clientHash);
$mf->errorHandler->setErrorMode(MailfireErrorHandler::MODE_EXCEPTION);

Set curl options for single request

$mf = new Mailfire($clientId, $clientHash);
$mf->request->setOption(CURLOPT_TIMEOUT, 2);

Set curl options for multiple requests (permanent)

$mf->request->setOption(CURLOPT_TIMEOUT_MS, 2000, true);

Reset permanent curl options

$mf->request->resetPermanentOptions();

HOW TO RUN THE TESTS

Make sure you have PHPUnit installed.

Run PHPUnit in the mailfire repo base directory.

./test.sh