Welcome
The Dynosend API (version 1.07) is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
The Dynosend API may differ as we release new updates for the application over time. Log in to your Dynosend dashboard to see the particular version, API base URI and authentication key.
Installation
To install the Dynosend API PHP library, you just have to run this command:
composer require rolocost/dynosendphp
Or download the package from GitHub:
https://github.com/Rolocost/dynosendphp
Authentication
Dynosend API employs simple Token Authentication which is also referred to as Bearer Authentication. That is, every Dynosend user account has an authentication token:
$client = new \DynosendSDK\Client('API_TOKEN');
Rate limit
Dynosend API relies on a simple rate limit to provide a predictably pleasant experience for customers and to protect our systems.
10 requests for each user per second
One-click login
Sometimes it is useful to have a one-click login URL so you can login to your Dynosend dashboard without having to enter your email or password. It is also helpful when you integrate Dynosend with another application so you can use a one-click login link without the need of a complicated authentication mechanism like SSO.
You just need to use these lines of code to get a one-time login token as well as the one-time login URL
Parameters
$client = new \DynosendSDK\Client('API_TOKEN');
$client->loginToken();
{
"token": "8vunPVPUDBMGYOEk9",
"url": "https://app.dynosend.com/login/token/8vunPVPUDBMGYOEk9"
}
Audiences
Audiences also referred to as mail lists, are at the center of email marketing management systems. It is designed to help you collect and manage subscribed and non-subscribed contacts. Dynosend's API allows you to create and edit your audiences as well as manage your contacts.
• View audiences
Retrieve all your audiences as well as every detail like name, description, etc. You can also find every audience uid. You can find it on your audiences page when logged in which is used as reference key for a particular audience.
Parameters
$client = new \DynosendSDK\Client('API_TOKEN');
$client->audience()->all();
[
{
"id": 1,
"uid": "5fade5c93e42a",
"name": "Audience 1",
"default_subject": "An Awesome Subject",
"from_email": "support@abccorp.com",
"from_name": "Customer Support",
"status": null,
"created_at": "2021-12-04T07:29:24.000000Z",
"updated_at": "2021-12-04T07:29:24.000000Z"
},
{
"id": 2,
"uid": "5fc9e55410e10",
"name": "Audience 2",
...
},
...
]
• Get audience details
Get detailed information of an audience identified by a given list_uid passed to the API call.
Parameters
$client = new \DynosendSDK\Client('API_TOKEN');
$client->audience()->find('LIST_UID');
{
"audience": {
"uid": "5fc9e55410e10",
"name": "List 1",
"default_subject": "Welcome to ABC Corp.",
"from_email": "admin@abccorp.org",
"from_name": "ABC Corp.",
"status": null,
"created_at": 2021-12-04T07:29:24.000000Z,
"updated_at": 2021-12-04T07:29:24.000000Z,
"fields": [
{
"label": "Email",
"type": "text",
"tag": "EMAIL",
"default_value": null,
"visible": "1",
"required": true,
"custom_order": null
},
{
"label": "Date of birth",
"type": "date",
"tag": "BIRTHDATE",
...
},
..
]
},
"contact_information": {
"company": "ABC Corp.",
"address_1": "9316 AVALON",
"address_2": "",
"country": "United States",
"state":"California",
"zip": "90003",
"phone": "+18002223333",
"url": "https://www.abccorp.org/",
"email": "info@abccorp.org",
"city": "Noname"
},
"statistics": {
"subscriber_count": 0,
"open_uniq_rate": 0,
"click_rate": 0,
"subscribe_rate": 0,
"unsubscribe_rate": 0,
"unsubscribe_count": 0,
"unconfirmed_count": 0
}
}
• Create custom field
Beside email field, you can add customized fields to your audiences to store more information about your audience's contacts such as their preferences, scores, plan names etc. and you can also segment your contacts based on field value and more.
Parameters
⊥ : Optional.
$client = new \DynosendSDK\Client('API_TOKEN');
$client->audience()->addCustomField('LIST_UID', [
'type' => 'text',
'label' => 'Plan name',
'tag' => 'PLAN',
'default_value' => 'Free trial'
]);
{
"id": 1,
"status": 1,
"message": "Custom field created",
"field": {
"mail_list_id": 2,
"type": "text",
"label": "Custom",
"tag":"CUSTOM_FIELD_1",
"uid":"5fcae3cb6298f",
"updated_at":"2021-12-04T07:29:24.000000Z",
"created_at":"2021-12-04T07:29:24.000000Z",
}
}
Contacts
By definition, a contact or subscriber is usually someone who is a member of one or more of your lists.
They may have subscribed themselves to your audience via a subscription page or web form, or you may have imported their details from another source like CSV, API, manually or using integrations.
• Get all contacts
View all contacts of a given audiences identified by a list_uid
Parameters
⊥ : Optional.
$client = new \DynosendSDK\Client('API_TOKEN');
$client->contact()->all([
'list_uid' => 'LIST_UID',
'per_page' => 20,
'page' => 1
]);
[
{
"uid": "5fd07b8b65284",
"email": "john@example.com",
"status": "subscribed",
"FIRST_NAME": "John",
"LAST_NAME": "Doe",
"CUSTOM_FIELD_1": "test"
},
...
]
• Create contact
Add a contact to an audience identified by a list_uid. Once added, the contact's status would be either subscribed or unconfirmed depending on your audience settings (single opt-in or double opt-in) and they might receive a verification email in case you have double opt-in activated.
Parameters
⊥ : Optional.
$client = new \DynosendSDK\Client('API_TOKEN');
$client->contact()->create([
'EMAIL' => 'john@example.com',
'list_uid' => 'LIST_UID',
'tag' => 'tag, another tag',
'OTHER_FIELD' => ...
]);
{
"status": 1,
"message": "Contact has been created",
"contact_uid": "5fd07b8b65284"
}
• Get contact details
Get detailed information of a contact identified by an email for a specific audience.
Parameters
$client = new \DynosendSDK\Client('API_TOKEN');
$client->contact()->identify('email',['list_uid' => 'LIST_UID']);
{
"contact": {
"contact_uid":"5fd07b8b65284",
"email":"john@example.com",
"status":"subscribed",
"source":null,
"ip_address":null,
"FIRST_NAME":"John",
"LAST_NAME":"Doe",
"CUSTOM_FIELD_1":"test"
...
}
}
• Update contact
Update information of a contact identified by an email for a specific audience.
Parameters
⊥ : Optional.
$client = new \DynosendSDK\Client('API_TOKEN');
$client->contact()->update('email',[
'EMAIL' => 'email',
'list_uid' => 'LIST_UID',
'tag' => 'new tags',
'OTHER_FIELDS' => ...
]);
{
"status": 1,
"message": "Contact has been updated",
"contact_uid": "5fd07b8b65284"
}
• Tag contact
Add a tag to a contact identified by an email for a specific audience.
Parameters
$client = new \DynosendSDK\Client('API_TOKEN');
$client->contact()->addtag([
'email' => 'email',
'list_uid' => 'LIST_UID',
'tag' => 'your added tags'
]);
{
"status": 1,
"message": "Tag added",
"contact_uid": "5fd07b8b65284"
"tags": [
"foo",
"bar",
"tag with space",
"yourtag"
]
}
• Find contact in all audiences
In Dynosend, a contact is identified by a unique uid and also by their email address and they may belong to more than one audience with different values. For example, a contact may have different names in different audiences.
With this method you will be able to retrieve all contacts with the same email in all audiences.
Parameters
$client = new \DynosendSDK\Client('API_TOKEN');
$client->contact()->findInAudiences('email');
{
"contacts": [
{
"contact_uid":"5fd07b8b65284",
"list_uid":"5fc9e55410e10",
"email":"john@example.com",
"status":"subscribed",
"source":null,
"ip_address":null,
"FIRST_NAME":"John",
"LAST_NAME":"Doe",
"CUSTOM_FIELD_1":null
},
{
"contact_uid":"0gd8uvi201350",
"list_uid":"5gc9u25710j96",
"email":"carl@example.com",
"status":"unsubscribed",
"source":"api",
...
}
]
}
• Send an event
Send an event from your own application to Dynosend. For example, when a subscriber identified by email performs any specific action like completing a form or a purchase and more.
Parameters
$client = new \DynosendSDK\Client('API_TOKEN');
$client->event()->sendevent([
'event_name' => 'account_created',
'email' => 'email',
'list_uid' => 'LIST_UID'
]);
{}
• Subscribe a contact
Subscribe a contact in your audience identified by an email for a specific audience. The contact's status would be changed to subscribed
Parameters
$client = new \DynosendSDK\Client('API_TOKEN');
$client->contact()->subscribe('email',['list_uid' => 'LIST_UID']);
{
"status": 1,
"message": "Subscribed"
}
• Unsubscribe a contact
Unsubscribe a contact in your audience identified by an email for a specific audience. The contact's status would be changed to unsubscribed
Parameters
$client = new \DynosendSDK\Client('API_TOKEN');
$client->contact()->unsubscribe('email',['list_uid' => 'LIST_UID']);
{
"status": 1,
"message": "Unsubscribed"
}
• Delete a contact
Delete a subscriber from an audience identified by an email for a specific audience.
Parameters
$client = new \DynosendSDK\Client('API_TOKEN');
$client->contact()->deletecontact('email',['list_uid' => 'LIST_UID']);
{
"status": 1,
"message": "Deleted"
}
Campaigns
A broadcast email marketing campaign is a coordinated set of individual email messages that are deployed across a specific period of time with one specific purpose. These specific purposes or calls-to-action (CTAs) can include the following: download an application, sign up for a webinar, or make a purchase. Dynosend allows you to create a marketing campaign targeting one or more lists of your audience. You can also set up a campaign that targets a segment of a given audience, rather than the entire audience.
• View campaigns
List all your campaigns including New, Running, Paused and Sent(done) ones.
Parameters
$client = new \DynosendSDK\Client('API_TOKEN');
$client->campaign()->all();
[
{
"uid":"5fb48ff221b27",
"name":"My Awesome Campaign",
"type":"regular",
"subject":"An Awesome Subject",
"from_email": "marketing@abccorp.com",
"from_name":"No Reply",
"reply_to":"support@abccorp.com",
"status":"new",
"delivery_at":null,
"created_at":"2022-09-01T09:38:47.000000Z",
"updated_at":"2022-09-01T09:45:16.000000Z"
},
...
]
• Get campaign details
Get detailed information and statistics of a campaign identified by a uid code.
Parameters
$client = new \DynosendSDK\Client('API_TOKEN');
$client->campaign()->find('uid');
{
"campaign": {
"uid":"5fb48ff221b27",
"name":"Untitled",
"audience":"",
"segment":"",
"default_subject":null,
"from_email":"marketing@abccorp.com",
"from_name":"Marketing Department",
"status":"new",
"created_at":"2021-12-04T07:29:24.000000Z",
"updated_at":"2021-12-04T07:29:24.000000Z"
},
"statistics": {
"subscriber_count":160,
"delivered_rate":0.99,
"open_count":98,
"unique_open_rate":0.25,
"unique_open_count":88,
"click_rate":"3",
"click_per_unique_open":0.5,
"click_count":16,
"abuse_feedback_count":0,
"last_click":"2021-12-04T11:17:30.000000Z",
"last_open":"2021-12-04T12:17:30.000000Z",
"bounce_count":0,
"unsubscribed":1,
"links":[],
"top_open_contacts":[
{
"uid": "605z55a6450fq",
"email": "name@gmail.com"
}
]
}
}
• Send a campaign
Send a configured campaign (after you create it on your Dynosend account) identified by a uid code.
Parameters
$client = new \DynosendSDK\Client('API_TOKEN');
$client->campaign()->send('uid');
{
"message": "Campaign started!",
}
• Pause a campaign
Pause a sending campaign identified by a uid code.
Parameters
$client = new \DynosendSDK\Client('API_TOKEN');
$client->campaign()->pause('uid');
{
"message": "Campaign paused!",
}
• Resume a campaign
Resume a paused campaign identified by a uid code.
Parameters
$client = new \DynosendSDK\Client('API_TOKEN');
$client->campaign()->resume('uid');
{
"message": "Campaign resumed!",
}