mailfire/php-sdk

此包已被废弃且不再维护。未建议替代包。

Mailfire PHP SDK

维护者

详细信息

github.com/mailfire/php-sdk

安装数: 42,414

依赖者: 0

建议者: 0

安全: 0

星标: 7

关注者: 5

分支: 2

此包尚未发布版本，信息有限。

README

##已弃用。需要询问支持以获取新版本。

开始

您可以安装PHP SDK

composer require mailfire/php-sdk

或者通过cURL/任何方式发起HTTP请求

通过认证签名请求

# PHP SDK
$clientId = 123;
$clientToken = 'a1s2d3f4g5h6j7k8l';
$mf = new Mailfire($clientId, $clientToken);
# PHP cURL
curl_setopt($ch, CURLOPT_USERPWD, '123:' . sha1('a1s2d3f4g5h6j7k8l'));
# console cURL
curl -u 123:957081746b54977d51bef9fc74f4d4fd023bab13

# 957081746b54977d51bef9fc74f4d4fd023bab13 is sha1 of clientToken (a1s2d3f4g5h6j7k8l)

通过PHP SDK发送邮件

// 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

// User will be autocreated via any first letter

// 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);
//

通过cURL发送邮件

curl -X POST https://api.mailfire.io/v1/push/system \
    -u 123:957081746b54977d51bef9fc74f4d4fd023bab13 \
    -d 'JSON_DATA'

# or https://api.mailfire.io/v1/push/trigger for trigger letters
# 957081746b54977d51bef9fc74f4d4fd023bab13 is sha1 of clientToken (a1s2d3f4g5h6j7k8l)
JSON_DATA
{
    "type_id": 1,
    "category": 1,
    "client_id": 123,
    "project_id": 1,
    "data": {
        "user": {
            "email": "test@example.com",
            "name": "John",
            "age": 22,
        },
        "some": "hi",
        "letter": "John",
        "variables": "!",
    },
    "meta": {
        "tracking_id": 72348234,
    }
}

其他API方法

检查邮件

$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,
) */
curl -X POST https://api.mailfire.io/v1/email/check \
    -u 123:957081746b54977d51bef9fc74f4d4fd023bab13 \
    -d '{"email":"Test@Example.com"}'

通过发送验证邮件

$result = $mf->email->validate($projectId, 'Test@Example.com');
/* Returned array(
  'orig' => 'Test@Example.com',
  'valid' => false, // result
  'reason' => 'send_fail', // reason of result
  'email' => 'test@example.com', // fixed email
  'vendor' => 'Unknown', // vendor name like Gmail
  'domain' => 'example.com',
  'trusted' => false,
  'is_send': true
) */
curl -X POST https://api.mailfire.io/v1/email/check/send \
    -u 123:957081746b54977d51bef9fc74f4d4fd023bab13 \
    -d '{"email":"Test@Example.com","project": 9}'

通过邮箱和项目获取用户信息

$projectId = 1;
$user = $mf->user->getByEmail('test@example.com', $projectId);
/* Returned array(
    "id": 8424, // USED IN MOST API METHODS
    "project_id":1,
    "email":"test@example.com",
    "name":"John",
    ...
) */
curl -X GET https://api.mailfire.io/v1/user/project/1/email/test@example.com \
    -u 123:957081746b54977d51bef9fc74f4d4fd023bab13

退订

$projectId = 1;
$user = $mf->user->getByEmail('test@example.com', $projectId);
$unsub = $mf->unsub->addBySettings($user);
// $user - array with $user[id] == 8424 (our user id)
// addBySettings reason == 9
curl -X POST https://api.mailfire.io/v1/unsub/8424/source/9 \
    -u 123:957081746b54977d51bef9fc74f4d4fd023bab13

重新订阅

$projectId = 1;
$user = $mf->user->getByEmail('test@example.com', $projectId);
// Make DELETE to /unsub/USER_ID
$unsub = $mf->unsub->subscribe($user);
curl -X DELETE https://api.mailfire.io/v1/unsub/8424 \
    -u 123:957081746b54977d51bef9fc74f4d4fd023bab13

管理员退订

$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)
}
*/
curl -X POST https://api.mailfire.io/v1/unsub/admin/1/email/dGVzdEBleGFtcGxlLmNvbQ== \
    -u 123:957081746b54977d51bef9fc74f4d4fd023bab13

# 'dGVzdEBleGFtcGxlLmNvbQ==' - base64_encode(test@example.com)

检查是否已退订

按用户

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

按邮箱和项目

$projectId = 1;
$unsub = $mf->unsub->isUnsubByEmailAndProjectId('test@example.com', $projectId); // Returns false(if not unsubscribed) or unsub data
curl -X GET https://api.mailfire.io/v1/unsub/isunsub/5234 \
    -u 123:957081746b54977d51bef9fc74f4d4fd023bab13

# 5234 - user_id

获取退订原因

$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"
}
curl -X GET https://api.mailfire.io/v1/unsub/unsubreason/5234 \
    -u 123:957081746b54977d51bef9fc74f4d4fd023bab13

# 5234 - user_id

获取退订列表

<?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"
    ],
    // ...
];
curl -X GET https://api.mailfire.io/v1/unsub/list/1262307661 \
    -u 123:957081746b54977d51bef9fc74f4d4fd023bab13

# timestamp(2010-01-01) = 1262307661

从类型退订

获取当前退订

$projectId = 1;
$user = $mf->user->getByEmail('test@example.com', $projectId);
$list = $mf->unsubTypes->getList($user);
//returns array {
//  [0] =>
//  array(3) {
//    'type_id' =>
//   int(3)
//    'unsubscribed' =>
//    bool(false)
//    'name' =>
//    string(11) "Popular now"
//  },
//  ...
//}
curl -X GET https://api.mailfire.io/v1/unsubtypes/5234 \
    -u 123:957081746b54977d51bef9fc74f4d4fd023bab13

# 5234 - user_id

用户从类型4和5退订

$mf->unsubTypes->addTypes($user, [4, 5]);
curl -X POST https://api.mailfire.io/v1/unsubtypes/nodiff/[MF_USER_ID] \
    -u 123:957081746b54977d51bef9fc74f4d4fd023bab13 \
    -d '{"type_ids": [4, 5]}'

用户重新订阅到类型4和5

$mf->unsubTypes->removeTypes($user, [4, 5]);
curl -X DELETE https://api.mailfire.io/v1/unsubtypes/nodiff/[MF_USER_ID] \
    -u 123:957081746b54977d51bef9fc74f4d4fd023bab13 \
    -d '{"type_ids": [4, 5]}'

用户重新订阅到所有类型

$mf->unsubTypes->removeAll($user); 
curl -X DELETE https://api.mailfire.io/v1/unsubtypes/all/[MF_USER_ID] \
    -u 123:957081746b54977d51bef9fc74f4d4fd023bab13

用户

用户信息

$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",
    ...
) */
curl -X GET https://api.mailfire.io/v1/user/project/1/email/test@example.com \
    -u 123:957081746b54977d51bef9fc74f4d4fd023bab13

创建和更新用户数据

$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
];

通过邮箱和项目ID

$result = $mf->user->setUserFieldsByEmailAndProjectId('ercling@yandex.ru', 2, $fields);
// $result is a boolean status
curl -X PUT https://api.mailfire.io/v1/userfields/project/1/emailhash/dGVzdEBleGFtcGxlLmNvbQ== \
    -u 123:957081746b54977d51bef9fc74f4d4fd023bab13 \
    -d 'JSON_DATA'

# 'dGVzdEBleGFtcGxlLmNvbQ==' - base64_encode(test@example.com) 
JSON_DATA
{
    "name": "John Dou",
    "gender": "m",
    "age": 21,
    "photo": "http://moheban-ahlebeit.com/images/Face-Wallpaper/Face-Wallpaper-26.jpg",
    "ak": "FFZxYfCfGgNDvmZRqnELYqU7",
    "vip": 1,
    "language": "es",
    "country": "esp",
    "platform_id": 1,
    "list_id": 1,
    "status": 0, 
    "partner_id": 1,
    "field1": 542,
    "sessions_count": 22,
    "session_last": 1498137772
}

按用户

$user = $mf->user->getById(892396028);
$result = $mf->user->setUserFieldsByUser($user, $fields);
// $result is a boolean status
curl -X PUT https://api.mailfire.io/v1/userfields/user/5234 \
    -u 123:957081746b54977d51bef9fc74f4d4fd023bab13 \
    -d 'JSON_DATA'

# 5234 - user_id
JSON_DATA
{
    "field1": 542,
    "field2": 22,
    "field3": 1498137772
}

获取用户自定义字段

$result = $mf->user->getUserFieldsByEmailAndProjectId('ercling@yandex.ru', 1);
// or
$result = $mf->user->getUserFieldsByUser($user);
/*
Returns [
    'user' => [
        'id' => 892396028,
        'project_id' => 1,
         ...
    ],
    'custom_fields' => [
        'sessions_count' => 22,
         ...
    ],
]
*/
curl -X GET https://api.mailfire.io/v1/userfields/user/5234\
    -u 123:957081746b54977d51bef9fc74f4d4fd023bab13

# 5234 - user_id     
curl -X GET https://api.mailfire.io/v1/userfields/project/1/email/test@example.com \
    -u 123:957081746b54977d51bef9fc74f4d4fd023bab13

在线

按用户ID更新在线状态

$mf->user->setOnlineByUser($user, new \DateTime());
curl -X PUT https://api.mailfire.io/v3/users/5234/online \
    -u 123:957081746b54977d51bef9fc74f4d4fd023bab13 \
    -d 'JSON_DATA'

# 5234 - user_id 
JSON_DATA
{
    "timestamp": "2010-01-01T08:15:30-01:00",
    "user_id": 5234
}

按用户邮箱更新在线状态

$mf->user->setOnlineByEmailAndProjectId('ercling@gmail.com', 1, new \DateTime());
curl -X PUT https://api.mailfire.io/v3/users/project/1/email/dGVzdEBleGFtcGxlLmNvbQ==/online \
    -u 123:957081746b54977d51bef9fc74f4d4fd023bab13 \
    -d 'JSON_DATA'

# 'dGVzdEBleGFtcGxlLmNvbQ==' - base64_encode(test@example.com) 
JSON_DATA
{
    "timestamp": "2010-01-01T08:15:30-01:00",
    "project_id": 1,
    "encoded_email": "dGVzdEBleGFtcGxlLmNvbQ==" 
}

支付

$startDate = 1509617696; // Payment date or subscription start date 
$expireDate = 1609617696; //optional (default false)
$paymentCount = 14; //optional (default false)
$paymentType = 1; // optional (default false)
$amount = 20; // optional (default false)

通过邮箱和项目ID

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

按用户

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

尝试发送错误数据

$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"
//  }
//}

产品目标

$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);

成功响应

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

错误响应

/*
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"
  }
}
*/

无需 SDK 发送目标

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

请求格式

名称 类型 描述
type string 必需。 目标类型
email string 必需。 用户电子邮件
project_id int 必需。 您项目的 ID。您可以在 https://admin.mailfire.io/account/projects 找到它
mail_id int 用户实现目标后的邮件 ID

产品上的客户端 ID

$email = 'john@gmail.com';
$projectId = 1;
$clientUserId = 1;

$mf->clientUser->create($email, $projectId, $clientUserId);

产品事件

数据格式

名称 类型 描述
project_id int 必需。 用户项目 ID
event_id int 必需。 事件 ID
uid bigint 必需。 您产品中事件从 uid
receiver_id int 必需。 发生事件的 Mailfire 用户 ID
sender_id int 与 receiver_id 关联的 Mailfire 用户 (id)
sender_product_id int 与 receiver_id 关联的产品用户 (id)
date string 事件日期。例如: '2018-10-24 19:40:22' 
        $projectId = 1;
        $eventId = 1;
        $uid = 1;
        $receiverId = 1;
        $senderId = 1;
        $senderProductId = 1;
        $date = '2018-10-24 19:40:22';

        $event = [
            'project_id' => $projectId,
            'event_id' => $eventId,
            'uid' => $uid,
            'receiver_id' => $receiverId,
            'sender_id' => $senderId,
            'sender_product_id' => $senderProductId,
            'date' => $date,
        ];
        
        $events[] = $event;
        
        $mf->event->send($events);

其他

获取响应（如果 $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"
//  }
//}

错误处理

默认情况下，任何错误消息（除 Mailfire 构造函数中的 InvalidArgumentException 之外）都收集在 error_log 中。如果您想组件抛出异常，只需更改处理程序模式即可

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

为单个请求设置 curl 选项

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

为多个请求设置 curl 选项（永久）

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

重置永久 curl 选项

$mf->request->resetPermanentOptions();

ee76563... 的父级删除 README.md