PHPackages                             sendwithus/api - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Mail & Notifications](/categories/mail)
4. /
5. sendwithus/api

ActiveLibrary[Mail & Notifications](/categories/mail)

sendwithus/api
==============

sendwithus.com PHP Client

v6.5.1(3mo ago)21853.5k↑23.6%19[1 issues](https://github.com/sendwithus/sendwithus_php/issues)2Apache-2.0PHPCI passing

Since Apr 27Pushed 3mo ago23 watchersCompare

[ Source](https://github.com/sendwithus/sendwithus_php)[ Packagist](https://packagist.org/packages/sendwithus/api)[ RSS](/packages/sendwithus-api/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (1)Versions (22)Used By (2)

sendwithus\_php
===============

[](#sendwithus_php)

Sendwithus PHP Client

Status
------

[](#status)

[![Build Status](https://camo.githubusercontent.com/82d8568d53a93fa485183969c7a61534a0954ba466c50974b296c9afcd00de4c/68747470733a2f2f7472617669732d63692e6f72672f73656e647769746875732f73656e647769746875735f7068702e706e67)](https://travis-ci.org/sendwithus/sendwithus_php)

Requirements
------------

[](#requirements)

```
curl library must be installed and enabled in php.ini

```

Install it via Composer
-----------------------

[](#install-it-via-composer)

Add it to your composer.json

```
{
    "require": {
        "sendwithus/api": "^6.4"
    }
}
```

Then install it with

```
composer install

```

Getting started
---------------

[](#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_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);
```

Emails
======

[](#emails)

Get emails
----------

[](#get-emails)

```
$response = $api->emails();
```

Get specific template
---------------------

[](#get-specific-template)

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

Create emails
-------------

[](#create-emails)

### Create new email

[](#create-new-email)

*We validate all HTML content*

```
$response = $api->create_email('Email Name',               // string email name
    'Email Subject',                                       // string subject line of email
    'Valid HTML',    // string of HTML code for email
    'Optional text content')                               // optional string of text for email
```

### Create new email template version

[](#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
    'Valid HTML',    // string block of HTML code used for email
    'Optional text content')                               // optional string of text used for email
```

### Update email version

[](#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
    'Valid HTML',    // string block of HTML code used for email
    'Optional text content')                               // optional string of text used for email
```

Send emails
-----------

[](#send-emails)

*NOTE* - If a customer does not exist by the specified email (recipient address), the send call will create a customer.

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

Send Examples
-------------

[](#send-examples)

### Send request with REQUIRED parameters only

[](#send-request-with-required-parameters-only)

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

### Send request with REQUIRED and OPTIONAL parameters

[](#send-request-with-required-and-optional-parameters)

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

### Send an email with multiple CC/BCC recipients

[](#send-an-email-with-multiple-ccbcc-recipients)

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

### Send an email with a dynamic tag

[](#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

[](#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

[](#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 an inline encoded image attachment

[](#send-email-with-an-inline-encoded-image-attachment)

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

### Send email with attachments

[](#send-email-with-attachments)

```
$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 templates
----------------

[](#render-templates)

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

### Example:

[](#example)

```
$response = $api->render('email_id',
    array('address' => 'us@sendwithus.com'),
    array(
        'template_data' => array(
            'name' => 'Bobby Boucher'
        )
    )
);
```

Get a Specific Email's Log
--------------------------

[](#get-a-specific-emails-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
)
```

Resend a Specific Email from Log
--------------------------------

[](#resend-a-specific-email-from-log)

```
resend(
    $log_id          // id of log to resend
)
```

Example

```
$response = api->resend('log_d4R7hV4d0r')
```

Response

```
(
    [status] => OK
    [receipt_id] => 130be975-dc07-4071-9333-58530e5df052-i03a5q
    [email] => stdClass Object
        (
            [locale] => en-US
            [version_name] => Test Template
            [name] => test
        )

    [success] => 1
)
```

Drip Unsubscribe
----------------

[](#drip-unsubscribe)

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

Drip Unsubscribe Example
------------------------

[](#drip-unsubscribe-example)

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

Drips 2.0
---------

[](#drips-20)

### List Drip Campaigns

[](#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

[](#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

```
$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

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

[](#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

[](#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
-------------

[](#customers-api)

### Create Customer

[](#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.
)
```

Example

```
$response = $api->create_customer('us@sendwithus.com',
    array('name' => 'Sendwithus')
);
```

### Update Customer

[](#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)

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

Example

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

### List Customer Logs

[](#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
)
*/
```

Batch API
---------

[](#batch-api)

Batch requests together to be run all at once.

### Usage

[](#usage)

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.

### Example

[](#example-1)

```
$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.
```

### Canceling Batch Request

[](#canceling-batch-request)

Sometimes it is necessary to cancel all the api requests that have been batched, but not yet sent. To do that, use `cancel()`:

### Example

[](#example-2)

```
$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.

Tests
-----

[](#tests)

### Running Unit Tests

[](#running-unit-tests)

Make sure to have phpunit installed () and run the following from the root directory

```
phpunit test
```

Troubleshooting
===============

[](#troubleshooting)

General Troubleshooting
-----------------------

[](#general-troubleshooting)

- Enable debug mode
- Make sure you're using the latest PHP client
- Make sure `data/ca-certificate.pem` is included. This file is *required*
- Capture the response data and check your logs — often this will have the exact error

Enable Debug Mode
-----------------

[](#enable-debug-mode)

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](https://www.sendwithus.com/docs/api "Official Sendwithus API Docs").

```
$API_KEY = 'THIS_IS_AN_EXAMPLE_API_KEY';
$options = array(
    'DEBUG' => true
);

$api = new API($API_KEY, $options);
```

Response Ranges
---------------

[](#response-ranges)

Sendwithus' API typically sends responses back in these ranges:

- 2xx – Successful Request
- 4xx – Failed Request (Client error)
- 5xx – Failed Request (Server error)

If you're receiving an error in the 400 response range follow these steps:

- Double check the data and ID's getting passed to Sendwithus
- Ensure your API key is correct
- Make sure there's no extraneous spaces in the id's getting passed

*Note*: Enable Debug mode to check the response code.

###  Health Score

61

—

FairBetter than 99% of packages

Maintenance78

Regular maintenance activity

Popularity49

Moderate usage in the ecosystem

Community33

Small or concentrated contributor base

Maturity72

Established project with proven stability

 Bus Factor3

3 contributors hold 50%+ of commits

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~196 days

Recently: every ~665 days

Total

21

Last Release

110d ago

Major Versions

v2.14.0 → v3.0.02017-01-26

v3.0.0 → v4.0.02017-03-09

v4.0.0 → v6.0.02017-08-08

### Community

Maintainers

![](https://www.gravatar.com/avatar/4175121aa1cd8ee0c889ccaa37cd39da7631927856ebeb475b44b8f3e8429373?d=identicon)[sendwithus](/maintainers/sendwithus)

---

Top Contributors

[![demoore](https://avatars.githubusercontent.com/u/4121458?v=4)](https://github.com/demoore "demoore (68 commits)")[![mrmch](https://avatars.githubusercontent.com/u/522045?v=4)](https://github.com/mrmch "mrmch (62 commits)")[![troymcginnis](https://avatars.githubusercontent.com/u/4299551?v=4)](https://github.com/troymcginnis "troymcginnis (39 commits)")[![mariesta](https://avatars.githubusercontent.com/u/2746586?v=4)](https://github.com/mariesta "mariesta (27 commits)")[![nrempel](https://avatars.githubusercontent.com/u/540048?v=4)](https://github.com/nrempel "nrempel (16 commits)")[![FlipCodes](https://avatars.githubusercontent.com/u/42158158?v=4)](https://github.com/FlipCodes "FlipCodes (8 commits)")[![bvanvugt](https://avatars.githubusercontent.com/u/1531419?v=4)](https://github.com/bvanvugt "bvanvugt (8 commits)")[![phil-swu](https://avatars.githubusercontent.com/u/33069454?v=4)](https://github.com/phil-swu "phil-swu (7 commits)")[![turnerdev](https://avatars.githubusercontent.com/u/48462986?v=4)](https://github.com/turnerdev "turnerdev (6 commits)")[![jemeric](https://avatars.githubusercontent.com/u/32044810?v=4)](https://github.com/jemeric "jemeric (5 commits)")[![Moxuz](https://avatars.githubusercontent.com/u/87310820?v=4)](https://github.com/Moxuz "Moxuz (5 commits)")[![gschier](https://avatars.githubusercontent.com/u/587576?v=4)](https://github.com/gschier "gschier (5 commits)")[![philsch](https://avatars.githubusercontent.com/u/5527838?v=4)](https://github.com/philsch "philsch (4 commits)")[![sanjaykhadka](https://avatars.githubusercontent.com/u/4007112?v=4)](https://github.com/sanjaykhadka "sanjaykhadka (4 commits)")[![dmitry-vinogradov](https://avatars.githubusercontent.com/u/885985?v=4)](https://github.com/dmitry-vinogradov "dmitry-vinogradov (4 commits)")[![phil-ma](https://avatars.githubusercontent.com/u/9565865?v=4)](https://github.com/phil-ma "phil-ma (3 commits)")[![bogdanhadadeasv](https://avatars.githubusercontent.com/u/20773510?v=4)](https://github.com/bogdanhadadeasv "bogdanhadadeasv (3 commits)")[![buschjost](https://avatars.githubusercontent.com/u/352767?v=4)](https://github.com/buschjost "buschjost (3 commits)")[![uxsanjay](https://avatars.githubusercontent.com/u/12725034?v=4)](https://github.com/uxsanjay "uxsanjay (2 commits)")[![echobass](https://avatars.githubusercontent.com/u/53410?v=4)](https://github.com/echobass "echobass (2 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/sendwithus-api/health.svg)

```
[![Health](https://phpackages.com/badges/sendwithus-api/health.svg)](https://phpackages.com/packages/sendwithus-api)
```

###  Alternatives

[minishlink/web-push

Web Push library for PHP

1.9k12.0M53](/packages/minishlink-web-push)[laravel-notification-channels/twilio

Provides Twilio notification channel for Laravel

2587.7M12](/packages/laravel-notification-channels-twilio)[spatie/url-signer

Generate a url with an expiration date and signature to prevent unauthorized access

4422.3M16](/packages/spatie-url-signer)[mattketmo/email-checker

Throwaway email detection library

2742.0M5](/packages/mattketmo-email-checker)[laravel-notification-channels/discord

Laravel notification driver for Discord.

2371.3M11](/packages/laravel-notification-channels-discord)[eduardokum/laravel-mail-auto-embed

Library for embed images in emails automatically

1702.0M5](/packages/eduardokum-laravel-mail-auto-embed)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)