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.
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. The token must be sent in either the Authorization HTTP header:
Authorization: Bearer YOUR_API_TOKEN
Or as a query string parameter in the request URL, example:
https://api.dynosend.com/api/v1/audiences?api_token=YOUR_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.
It is as simple as making a GET request to /login-token to obtain a one-time login token as well as the one-time login URL
Parameters
curl -X POST -H "accept:application/json" -G \
https://api.dynosend.com/api/v1/login-token \
-d api_token={api_token}
{
"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
curl -X GET -H "accept:application/json" -G \
https://api.dynosend.com/api/v1/audiences \
-d api_token={api_token}
[
{
"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
curl -X GET -H "accept:application/json" -G \
https://api.dynosend.com/api/v1/audiences/{list_uid} \
-d api_token={api_token}
{
"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 common fields of a contact like emails, names, addresses, cellphone numbers, etc. 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.
curl -X POST -H "accept:application/json" -G \
https://api.dynosend.com/api/v1/audiences/{list_uid}/add-field \
-d api_token={api_token} \
-d type=text \
-d label=Custom \
-d tag=CUSTOM_FIELD_1
{
"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.
curl -X GET -H "accept:application/json" -G \
https://api.dynosend.com/api/v1/contacts \
-d api_token={api_token} \
-d list_uid={list_uid} \
-d per_page=20 \
-d 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.
curl -X POST -H "accept:application/json" -G \
https://api.dynosend.com/api/v1/contacts \
-d api_token={api_token} \
-d list_uid={list_uid} \
-d EMAIL=test@gmail.com \
-d tag=subscriber \
-d OTHER_FIELD=value
{
"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
curl -X GET -H "accept:application/json" -G \
https://api.dynosend.com/api/v1/contacts/{email} \
-d api_token={api_token} \
-d 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.
curl -X PATCH -H "accept:application/json" -G \
https://api.dynosend.com/api/v1/contacts/{email} \
-d api_token={api_token} \
-d list_uid={list_uid} \
-d EMAIL=test@gmail.com \
-d tag=foo,bar,tag+with+space \
-d OTHER_FIELD=Value
{
"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
curl -X PATCH -H "accept:application/json" -G \
https://api.dynosend.com/api/v1/contacts/addtag \
-d api_token={api_token} \
-d list_uid={list_uid} \
-d email=test@gmail.com \
-d tag=yourtag
{
"status": 1,
"message": "Tag added",
"contact_uid": "5fd07b8b65284"
"tags": [
"foo",
"bar",
"tag with space",
"yourtag"
]
}
• Find contact by email
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
curl -X GET -H "accept:application/json" -G \
https://api.dynosend.com/api/v1/contacts/email/{email} \
-d api_token={api_token} \
{
"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
curl -X POST -H "accept:application/json" -G \
https://api.dynosend.com/api/v1/events \
-d api_token={api_token} \
-d email=john@example.com \
-d list_uid=5fc9e55410e10 \
-d event_name=account_created
{}
• 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
curl -X PATCH -H "accept:application/json" -G \
https://api.dynosend.com/api/v1/contacts/{email}/subscribe \
-d api_token={api_token} \
-d 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
curl -X PATCH -H "accept:application/json" -G \
https://api.dynosend.com/api/v1/contacts/{email}/unsubscribe \
-d api_token={api_token} \
-d 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
curl -X DELETE -H "accept:application/json" -G \
https://api.dynosend.com/api/v1/contacts/{email} \
-d api_token={api_token} \
-d 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
curl -X GET -H "accept:application/json" -G \
https://api.dynosend.com/api/v1/campaigns \
-d api_token={api_token}
[
{
"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
curl -X GET -H "accept:application/json" -G \
https://api.dynosend.com/api/v1/campaigns/{uid} \
-d api_token={api_token}
{
"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
curl -X POST -H "accept:application/json" -G \
https://api.dynosend.com/api/v1/campaigns/{uid}/start \
-d api_token={api_token}
{
"message": "Campaign started!",
}
• Pause a campaign
Pause a sending campaign identified by a uid code.
Parameters
curl -X POST -H "accept:application/json" -G \
https://api.dynosend.com/api/v1/campaigns/{uid}/pause \
-d api_token={api_token}
{
"message": "Campaign paused!",
}
• Resume a campaign
Resume a paused campaign identified by a uid code.
Parameters
curl -X POST -H "accept:application/json" -G \
https://api.dynosend.com/api/v1/campaigns/{uid}/resume \
-d api_token={api_token}
{
"message": "Campaign resumed!",
}