sendwithus PHP Client
curl library must be installed and enabled in php.ini
Add it to your composer.json
{
"repositories": [
{
"type": "vcs",
"url": "https://github.com/sendwithus/sendwithus_php"
}
],
"require": {
"sendwithus/api": "dev-master"
}
}
Then install it with
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 = 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
$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
$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
$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
// Send function header
send(
$email_id, // string, id of email to send
$recipient, // associative array, ("address" => "ckent@dailyplanet.com", "name" => "Clark") to send to
$args // (optional) array, (array) additional parameters - (see below)
)
// Send function options
'email_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.
'files' // array, paths to files to attach to the send.
'tags' // array of strings to tag email send with.
'esp_account' // string of ESP ID to manually select ESP
$response = $api->send('email_id',
array('address' => 'us@sendwithus.com')
);
$response = $api->send('email_id',
array(
'name' => 'Matt',
'address' => 'us@sendwithus.com'),
array(
'email_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(
'email_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(
'files' => array(
'filename.txt',
'filename.pdf'
)
)
);
get_segments()
Example
$response = $api->get_segments();
Response
Array
(
[0] => stdClass Object
(
[created] => 1402378620
[id] => seg_0biVV4Ncf1234
[name] => TEST_SEGMENT
[object] => segment
)
)
send_segment(
$email_id, // id of template to send
$segment_id, // id of the segment to send to
$data // optional array of data to send
)
Example
$response = $api->send_segment(tem_123jeDI23, 'seg_0biVV4Ncf1234');
logs(
$count //The number of logs to return. Max: 100, Default: 100
$offset //Offset the number of logs to return. Default: 0
$created_gt //Return logs created strictly after the given UTC timestamp
$created_gte //Return logs created on or after the given UTC timestamp
$created_lt //Return logs created strictly before the given UTC timestamp
$created_lte //Return logs created on or before the given UTC timestamp
)
get_log(
$log_id // id of log to retrieve
)
Example
$response = api->get_log('log_d4R7hV4d0r')
Response
(
[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
)
// 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
Example
$response = $api->list_drip_campaigns();
Response
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
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
$email_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', $email_data, $args);
Response
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
$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
$response = $api->remove_from_drip_campaign('us@sendwithus.com', 'dc_1234abcd1234');
Response
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
$response = $api->drip_campaign_details(
$drip_campaign_id // string, drip campaign to list details from
);
Example
$response = $api->drip_campaign_details('dc_1234abcd1234');
Response
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.
// 'groups' - Default is null. Array of group IDs
)
Example
$response = $api->create_customer('us@sendwithus.com',
array('name' => 'Sendwithus')
);
update_customer(
$email, // string, email of customer
$data, // array, optional, data for customer
)
Example
$response = $api->update_customer('us@sendwithus.com',
array('name' => 'Sendwithus.com')
);
delete_customer(
$email, // string, email of customer
)
Example
$response = $api->delete_customer('us@sendwithus.com');
Adds a conversion event to recent templates for recipient
customer_conversion(
$email, // string, email of customer
$revenue, // integer, optional, amount in cents
);
Example (required parameters only)
$response = $api->customer_conversion('curtis@sendwithus.com');
print_r($response);
/*
stdClass Object
(
[status] => OK
[success] => 1
)
*/
Example (all parameters)
// $19.99 in revenue
$response = $api->customer_conversion('curtis@sendwithus.com', 1999);
print_r($response);
/*
stdClass Object
(
[status] => OK
[success] => 1
)
*/
Adds a customer to a specified group
add_customer_to_group('curtis@sendwithus.com', 'grp_jk2jejidi3');
Removes a customer from a specified group
remove_customer_from_group('curtis@sendwithus.com', 'grp_jk2jejidi3');
List all groups
Example
$response = $api->list_groups();
print_r($response->groups[0]);
/*
(
[id] => grp_nEozfaiWwBHW4Fsmc
[description] => An example group
[name] => Group name
)
*/
create_group(
$name, // string, name of group
$description, // string, optional, description for group
)
Example
$response = $api->create_group('Group name',
'An example group'
);
print_r($response);
/*
stdClass Object
(
[success] => 1
[group] => stdClass Object
(
[name] => Group name
[description] => An example group
[id] => grp_ooEDQKetS2Yqs7FSGAdReB
)
[status] => OK
)
*/
update_group(
$name, // string, name of group
$group_id // string id of group
$description, // string, optional, description for group
)
Example
$response = $api->update_group('Updated Group name',
'An example group updated description'
);
print_r($response);
/*
stdClass Object
(
[success] => 1
[group] => stdClass Object
(
[name] => Updated Group name
[description] => An example group updated description
[id] => grp_ooEDQKetS2Yqs7FSGAdReB
)
[status] => OK
)
*/
delete_group(
$group_id, // string, group_id of group
)
Example
$response = $api->delete_group('grp_ooEDQKetS2Yqs7FSGAdReB');
print $response->success; // true
print $response->status; // "OK"
print $response->receipt_id; // ### numeric receipt_id you can use to query email status later
print $response->success; // false
print $response->status; // "error"
print $response->exception; // Exception Object
print $response->code;
// 400 (malformed request)
// 403 (bad api key)
List all customer logs
Example
$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.
Create a batch_api object by calling start_batch()
.
Do any request you would do normally with the API but on the batch_api object.
Execute all commands at once by calling execute()
on the object.
$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()
:
$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.
Make sure to have phpunit installed (http://phpunit.de/) and run the following from the root directory
phpunit test