Wallogit.com
2017 © Pedro Peláez
sendwithus.com PHP Client
Sendwithus PHP Client, (*1)
, (*2)
curl library must be installed and enabled in php.ini
Add it to your composer.json, (*3)
{
"require": {
"sendwithus/api": "^6.4"
}
}
Then install it with, (*4)
composer install
// Yii Users
Yii::$classMap = array(
'sendwithus\\API' => dirname($_SERVER['DOCUMENT_ROOT']) . '/path/to/sendwithus/lib/API.php'
);
// composer users
use sendwithus\API;
require_once 'vendor/autoload.php';
$API_KEY = 'THIS_IS_A_TEST_API_KEY';
$options = array(
'DEBUG' => true,
'API_DEBUG_HANDLER' => function ($message, $priority_level) {
// possible priority levels - http://php.net/manual/en/function.syslog.php
error_log("[SendWithUs][$priority_level] " . $message);
}
);
$api = new API($API_KEY, $options);
$response = $api->emails();
$response = $api->get_template($template_id, //string id of template
$version_id //optional string version id of template
);
We validate all HTML content, (*5)
$response = $api->create_email('Email Name', // string email name
'Email Subject', // string subject line of email
'<html><head></head><body>Valid HTML<body></html>', // string of HTML code for email
'Optional text content') // optional string of text for email
We validate all HTML content, (*6)
$response = $api->create_new_template_version(
'Email Name', // string email version name
'Email Subject', // string subject of email
'tem_JAksjdjwJXUVwnemljflksEJks', // string id of email used
'<html><head></head><body>Valid HTML<body></html>', // string block of HTML code used for email
'Optional text content') // optional string of text used for email
We validate all HTML content, (*7)
$response = $api->update_template_version(
'Email Name', // string email version name
'Email Subject', // string subject of email
'tem_JAkCjdjwJXUVwnemljflksEJks', // string id of email being updated
'ver_iuweJskj4Jwkj2ndclk4jJDken', // string version of email being updated
'<html><head></head><body>Valid HTML<body></html>', // string block of HTML code used for email
'Optional text content') // optional string of text used for email
NOTE - If a customer does not exist by the specified email (recipient address), the send call will create a customer., (*8)
// Send function header
send(
$email_id, // string, id of email to send (template id)
$recipient, // associative array, ("address" => "ckent@dailyplanet.com", "name" => "Clark") to send to
$args // (optional) array, (array) additional parameters - (see below)
)
// Send function options
'template_data' // array of variables to merge into the template.
'sender' // array ("address", "name", "reply_to") of sender.
'cc' // array of ("address", "name") for carbon copy.
'bcc' // array of ("address", "name") for blind carbon copy.
'inline' // string, path to file to include inline
// or an associative array with "id" containing filename
// and "data" containing base64 encoded file content
'files' // array, each element represents either a string path to file to attach
// or an associative array with "id" containing filename
// and "data" containing base64 encoded file content
'tags' // array of strings to tag email send with.
'esp_account' // string of ESP ID to manually select ESP
'headers' // associative array of header name and value
$response = $api->send('email_id',
array('address' => 'us@sendwithus.com')
);
$response = $api->send('email_id',
array(
'name' => 'Matt',
'address' => 'us@sendwithus.com'),
array(
'template_data' => array('name' => 'Jimmy the snake'),
'sender' => array(
'name' => 'Company',
'address' => 'company@company.com',
'reply_to' => 'info@company.com'
),
'esp_account' => 'esp_EMpi5eo59cG4cCWd7AdW7J'
)
);
$response = $api->send('email_id',
array(
'name' => 'Matt',
'address' => 'us@sendwithus.com'
),
array(
'template_data' => array('name' => 'Jimmy the snake'),
'sender' => array(
'name' => 'Company',
'address' => 'company@company.com',
'reply_to' => 'info@company.com'
),
'cc' => array(
array(
'name' => 'CC Name',
'address' => 'CC@company.com'
),
array(
'name' => 'CC 2 Name',
'address' => 'CC2@company.com'
)
),
'bcc' => array(
array(
'name' => 'BCC Name',
'address' => 'BCC@company.com'
)
)
)
);
$response = $api->send('email_id',
array(
'name' => 'Matt',
'address' => 'us@sendwithus.com'),
array(
'tags' => array('Production', 'Client1')
)
);
$response = $api->send('email_id',
array(
'name' => 'Matt',
'address' => 'us@sendwithus.com'),
array(
'version_name' => 'My Version'
)
);
$response = $api->send('email_id',
array(
'name' => 'Matt',
'address' => 'us@sendwithus.com'),
array(
'inline' => 'filename.jpg'
)
);
$response = $api->send('email_id',
array(
'name' => 'Matt',
'address' => 'us@sendwithus.com'),
array(
'inline' => array(
'id' => 'photo.jpg',
'data' => base64_encode(file_get_contents('filename.jpg'))
)
)
);
$response = $api->send('email_id',
array(
'name' => 'Matt',
'address' => 'us@sendwithus.com'),
array(
'files' => array(
'filename.txt',
'filename.pdf',
array(
'id' => 'photo.jpg',
'data' => base64_encode(file_get_contents('filename.jpg'))
)
)
)
);
// Render function header
render(
$email_id, // string, id of email to send (template id)
$args // (optional) array, (array) additional parameters - (see below)
)
// Send function options
'template_data' // Array of variables to merge into the template.
'version_id' // Version ID obtained from /templates/(:template_id)/versions
'version_name' // Version name that you want rendered (provide either a version_name or a version_id, not both)
'locale' // Template locale to render
'strict' // Render in strict mode (fails on missing template data)
$response = $api->render('email_id',
array('address' => 'us@sendwithus.com'),
array(
'template_data' => array(
'name' => 'Bobby Boucher'
)
)
);
get_log(
$log_id // id of log to retrieve
)
Example, (*9)
$response = api->get_log('log_d4R7hV4d0r')
Response, (*10)
(
[email_id] => tem_1jeid84bg
[recipient_name] =>
[message] => Mandrill: Message has been successfully delivered to the receiving server.
[id] => log_d4R7hV4d0r
[object] => log
[created] => 1409287597
[email_name] => test
[recipient_address] => person@example.com
[status] => sent
[email_version] => Original Version
)
resend(
$log_id // id of log to resend
)
Example, (*11)
$response = api->resend('log_d4R7hV4d0r')
Response, (*12)
(
[status] => OK
[receipt_id] => 130be975-dc07-4071-9333-58530e5df052-i03a5q
[email] => stdClass Object
(
[locale] => en-US
[version_name] => Test Template
[name] => test
)
[success] => 1
)
// Unsubscribe email address from active drips
drip_unsubscribe(
$email_address, // the email to unsubscribe from active drips
)
$response = $api->drip_unsubscribe('us@sendwithus.com');
List all drip campaigns for the current profile, (*13)
Example, (*14)
$response = $api->list_drip_campaigns();
Response, (*15)
Array
(
[0] => stdClass Object
(
[drip_steps] => Array
(
[0] => stdClass Object
(
[id] => dcs_1234abcd1234
[object] => drip_step
[delay_seconds] => 0
[email_id] => tem_1234abcd1234
)
)
[name] => Drip Campaign
[enabled] => 1
[id] => dc_1234abcd1234
[trigger_email_id] => tem_1234abcd1234
[object] => drip_campaign
)
)
Starts a customer on the first step of a specified drip campaign, (*16)
start_on_drip_campaign(
$recipient_address, // string, email address being added to drip campaign
$drip_campaign_id, // string, drip campaign being added to
$data // array, (optional) email data being added to drip campaign
$args // array, (optional) additional options being sent with email (tags, cc's, etc)
);
// Args options
'sender' // array ("address", "name", "reply_to") of sender.
'cc' // array of ("address", "name") for carbon copy.
'bcc' // array of ("address", "name") for blind carbon copy.
'tags' // array of strings to tag email send with.
'esp_account' // string of ESP ID to manually select ESP
Example, (*17)
$template_data = array(
'name' => 'Jean-Luc',
'rank' => 'Captain'
);
$args = array(
'tags' => array('all', 'the', 'tags'),
'cc' => array('address' => 'them@sendwithus.com')
);
$response = $api->start_on_drip_campaign('us@sendwithus.com', 'dc_1234abcd1234', $template_data, $args);
Response, (*18)
stdClass Object
(
[success] => 1
[drip_campaign] => stdClass Object
(
[id] => dc_1234abcd1234
[name] => Drip Campaign
)
[message] => Recipient successfully added to drip campaign.
[status] => OK
[recipient_address] => us@sendwithus.com
)
Deactivates all pending emails for a customer on a specified drip campaign, (*19)
$response = $api->remove_from_drip_campaign(
$recipient_address, // string, email address being removed from drip campaign
$drip_campaign_id // string, drip campaign being removed from
);
Example, (*20)
$response = $api->remove_from_drip_campaign('us@sendwithus.com', 'dc_1234abcd1234');
Response, (*21)
stdClass Object
(
[success] => 1
[drip_campaign] => stdClass Object
(
[id] => dc_1234abcd1234
[name] => Drip Campaign
)
[message] => Recipient successfully removed from drip campaign.
[status] => OK
[recipient_address] => us@sendwithus.com
)
Show all the steps and other information in a specified campaign, (*22)
$response = $api->drip_campaign_details(
$drip_campaign_id // string, drip campaign to list details from
);
Example, (*23)
$response = $api->drip_campaign_details('dc_1234abcd1234');
Response, (*24)
stdClass Object
(
[drip_steps] => Array
(
[0] => stdClass Object
(
[id] => dcs_1234abcd1234
[object] => drip_step
[delay_seconds] => 0
[email_id] => tem_1234abcd1234
)
)
[name] => Drip Campaign
[enabled] => 1
[id] => dc_1234abcd1234
[trigger_email_id] => tem_1234abcd1234
[object] => drip_campaign
)
create_customer(
$email, // string, email of customer
$data, // array, optional, data for customer
$args // array, optional, optional parameters:
// The additional optional parameters are as follows:
// 'locale' - Default is null. String to specify a locale for this customer.
)
Example, (*25)
$response = $api->create_customer('us@sendwithus.com',
array('name' => 'Sendwithus')
);
update_customer(
$email, // string, email of customer
$data, // array, optional, data for customer
)
Example, (*26)
$response = $api->update_customer('us@sendwithus.com',
array('name' => 'Sendwithus.com')
);
delete_customer(
$email, // string, email of customer
)
Example, (*27)
$response = $api->delete_customer('us@sendwithus.com');
List all customer logs, (*28)
Example, (*29)
$response = api->get_customer_logs("email@email.com");
print_r($response);
/*
(
[success] => 1
[logs] => Array
(
[email_name] => Name of email
[message] => Message body
[recipient_name] => Recipient name
[email_version] => Name of email version
[object] => log
[email_id] => ID of email
[created] => Time stamp
[recipient_address] => Email address of recipient
[status] => Status of email
[id] => ID of log
)
[status] => OK
)
*/
Batch requests together to be run all at once., (*30)
Create a batch_api object by calling start_batch()., (*31)
Do any request you would do normally with the API but on the batch_api object., (*32)
Execute all commands at once by calling execute() on the object., (*33)
$batch_api = api->start_batch();
for($i = 0; $i < 10; $i++) {
$result = $batch_api->create_customer('us@sendwithus.com',
array('name' => 'Sendwithus'));
// $result->success == true && $result->status == 'Batched'
}
$result = $batch_api->execute();
// $result will be an array of responses for each command executed.
Sometimes it is necessary to cancel all the api requests that have been batched, but not yet sent.
To do that, use cancel():, (*34)
$batch_api = api->start_batch();
for($i = 0; $i < 10; $i++) {
$batch_api->create_customer('us@sendwithus.com',
array('name' => 'Sendwithus'));
}
$result = $batch_api->cancel();
// $result->success == true && $result->status == 'Canceled'
Once you have canceled a batch, you can continue to use the batch to make more requests., (*35)
Make sure to have phpunit installed (http://phpunit.de/) and run the following from the root directory, (*36)
phpunit test
data/ca-certificate.pem is included. This file is required
Debug mode prints out the underlying cURL information as well as the data payload that gets sent to Sendwithus. You will most likely find this information in your logs. To enable it, simply put "DEBUG" => true in the optional parameters when instantiating the API object. Use the debug mode to compare the data payload getting sent to sendwithus' API docs., (*37)
$API_KEY = 'THIS_IS_AN_EXAMPLE_API_KEY';
$options = array(
'DEBUG' => true
);
$api = new API($API_KEY, $options);
Sendwithus' API typically sends responses back in these ranges:, (*38)
If you're receiving an error in the 400 response range follow these steps:, (*39)
Note: Enable Debug mode to check the response code., (*40)