sendwithus_php

sendwithus PHP Client

status

requirements

curl library must be installed and enabled in php.ini

Install it via Composer

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

Getting started

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

Emails

Get emails

$response = $api->emails();

Get specific template

$response = $api->get_template($template_id,     //string id of template
                               $version_id       //optional string version id of template
);

Create emails

Create new email

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

Create new email template version

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

Update email version

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 emails

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

Send Examples

Send request with REQUIRED parameters only

$response = $api->send('email_id',
    array('address' => 'us@sendwithus.com')
);

Send request with REQUIRED and OPTIONAL parameters

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

Send an email with multiple CC/BCC recipients

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

Send an email with a dynamic tag

$response = $api->send('email_id',
    array(
        'name' => 'Matt',
        'address' => 'us@sendwithus.com'),
    array(
        'tags' => array('Production', 'Client1')
    )
);

Send specific version of an email

$response = $api->send('email_id',
    array(
        'name' => 'Matt',
        'address' => 'us@sendwithus.com'),
    array(
        'version_name' => 'My Version'
    )
);

Send email with an inline image attachment

$response = $api->send('email_id',
    array(
        'name' => 'Matt',
        'address' => 'us@sendwithus.com'),
    array(
        'inline' => 'filename.jpg'
    )
);

Send email with attachments

$response = $api->send('email_id',
    array(
        'name' => 'Matt',
        'address' => 'us@sendwithus.com'),
    array(
        'files' => array(
            'filename.txt',
            'filename.pdf'
        )
    )
);

Segments

Get segments

get_segments()

Example

$response = $api->get_segments();

Response

Array
(
    [0] => stdClass Object
        (
            [created] => 1402378620
            [id] => seg_0biVV4Ncf1234
            [name] => TEST_SEGMENT
            [object] => segment
        )

)

Send to a 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');

Get Email Logs

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 a Specific Email's Log

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
)

Drip Unsubscribe

// Unsubscribe email address from active drips
drip_unsubscribe(
    $email_address,      // the email to unsubscribe from active drips
)

Drip Unsubscribe Example

$response = $api->drip_unsubscribe('us@sendwithus.com');

Drips 2.0

List Drip Campaigns

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

Start on 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
)

Remove from Drip Campaign

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
)

List Drip Campaign Details

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
)

Customers API

Create Customer

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

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

delete_customer(
    $email,             // string, email of customer
)

Example

$response = $api->delete_customer('us@sendwithus.com');

Add Customer to Group

Adds a customer to a specified group

add_customer_to_group('curtis@sendwithus.com', 'grp_jk2jejidi3');

Remove Customer From Group

Removes a customer from a specified group

remove_customer_from_group('curtis@sendwithus.com', 'grp_jk2jejidi3');

Groups API

List Groups

List all groups

Example

$response = $api->list_groups();

print_r($response->groups[0]);

/*
(
    [id] => grp_nEozfaiWwBHW4Fsmc
    [description] => An example group
    [name] => Group name
)
*/

Create a Group

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 a Group

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

delete_group(
    $group_id,             // string, group_id of group
)

Example

$response = $api->delete_group('grp_ooEDQKetS2Yqs7FSGAdReB');

Expected response

Success

print $response->success; // true

print $response->status; // "OK"

print $response->receipt_id; // ### numeric receipt_id you can use to query email status later

Error cases

print $response->success; // false

print $response->status; // "error"

print $response->exception; // Exception Object

print $response->code;
// 400 (malformed request)
// 403 (bad api key)

List Customer Logs

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

Tests

Running Unit Tests

Make sure to have phpunit installed (http://phpunit.de/) and run the following from the root directory

phpunit test

buschjost/sendwithus_php

sendwithus_php

status

requirements

Install it via Composer

Getting started

Emails

Get emails

Get specific template

Create emails

Create new email

Create new email template version

Update email version

Send emails

Send Examples

Send request with REQUIRED parameters only

Send request with REQUIRED and OPTIONAL parameters

Send an email with multiple CC/BCC recipients

Send an email with a dynamic tag

Send specific version of an email

Send email with an inline image attachment

Send email with attachments

Segments

Get segments

Send to a Segment

Get Email Logs

Get a Specific Email's Log

Drip Unsubscribe

Drip Unsubscribe Example

Drips 2.0

List Drip Campaigns

Start on Drip Campaign

Remove from Drip Campaign

List Drip Campaign Details

Customers API

Create Customer

Update Customer

Delete Customer

Add Customer to Group

Remove Customer From Group

Groups API

List Groups

Create a Group

Update a Group

Delete Group

Expected response

Success

Error cases

List Customer Logs

Tests

Running Unit Tests