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.

600 API calls per minute

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 POST request to /login-token to obtain a one-time login token as well as the one-time login URL

Parameters
Paramter
Type
Description
api_token
string
Your API token. You can find it in your API main page when logged in.
Request: 
curl -X POST -H "accept:application/json" -G \
	https://api.dynosend.com/api/v1/login-token \
	-d api_token={api_token}
Response: 
{
    "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
Paramter
Type
Description
api_token
string
Your API token. You can find it in your API main page when logged in.
Request: 
curl -X GET -H "accept:application/json" -G \
    https://api.dynosend.com/api/v1/audiences \
    -d api_token={api_token}
Response: 
[
    {
        "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-11-13 01:47:53",
        "updated_at": "2021-12-04 07:29:24"
    },
    {
        "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
Paramter
Type
Description
api_token
string
Your API token. You can find it in your API main page when logged in.
list_uid
string
Audience uid. You can find it on your audiences page when logged in or can be retrieved from your database if you have saved it.
Request: 
curl -X GET -H "accept:application/json" -G \
    https://api.dynosend.com/api/v1/audiences/{list_uid} \
    -d api_token={api_token}
Response: 
{
    "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": [],
        "updated_at": [],
        "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
Paramter
Type
Description
api_token
string
Your API token. You can find it in your API main page when logged in.
list_uid
string
Audience uid. You can find it on your audiences page when logged in or can be retrieved from your database if you have saved it.
type
string
Choose one of these types: text, number, datetime.
label
string
Custom field label, visible on your dashboard, pages and embedded form.
tag
string
Tag name used to identify a custom field and can also be used as dynamic content when sending an email, may contain underscores (all capital).
default_value ⊥
string
Default value of the field. Can be left empty.

⊥ : Optional.

Request: 
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 \
    -d default_value=test
Response: 
{
    "status": 1,
    "message": "Custom field has created",
    "field": {
        "mail_list_id": 2,
        "type": "text",
        "label": "Custom",
        "tag":"CUSTOM_FIELD_1",
        "default_value":"test",
        "uid":"5fcae3cb6298f",
        "updated_at":"2020-12-05 01:35:07",
        "created_at":"2020-12-05 01:35:07","id":7
    }
}

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
Paramter
Type
Description
api_token
string
Your API token. You can find it in your API main page when logged in.
list_uid
string
Audience uid. You can find it on your audiences page when logged in or can be retrieved from your database if you have saved it.
per_page ⊥
integer
Number of contacts per page. Default: 20
page ⊥
integer
Page number if you have many contacts

⊥ : Optional.

Request: 
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
Response: 
[
    {
        "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
Paramter
Type
Description
api_token
string
Your API token. You can find it in your API main page when logged in.
list_uid
string
Audience uid. You can find it on your audiences page when logged in or can be retrieved from your database if you have saved it.
EMAIL
string
Contact's email address
tag ⊥
string
Contact's tag (e.g. subscriber, purchaser ...etc), comma separated if multiple. Different from custom field tag, this can be used to segment your contacts, trigger automations and more.
[OTHER_FIELDS...] ⊥
string
Add a custom field if you have created any for your audience.

⊥ : Optional.

Request: 
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
Response: 
{
    "status": 1,
    "message": "Contact has been created",
    "contact_uid": "5fd07b8b65284"
}
Recommended to store contact_uid it in your database for future use

• Get contact details

Get detailed information of a contact identified by an email for a specific audience.

Parameters
Paramter
Type
Description
api_token
string
Your API token. You can find it in your API main page when logged in.
email
string
Contact's email for identification.
list_uid
string
Audience uid. You can find it on your audiences page when logged in or can be retrieved from your database if you have saved it.
Request: 
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}
Response: 
{
    "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
Paramter
Type
Description
api_token
string
Your API token. You can find it in your API main page when logged in.
list_uid
string
Audience uid. You can find it on your audiences page when logged in or can be retrieved from your database if you have saved it.
email
string
Contact's email address for identification.
EMAIL
string
Can be the same contact's email address used for identification, or can be changed if you want to update it (but this will also change the email used for identification in the future).
tag ⊥
string
Overwrite all contact's tags (e.g. subscriber, purchaser ...etc), comma separated if multiple. Different from custom field tag, this can be used to segment your contacts, trigger automations and more.
[OTHER_FIELD...] ⊥
string
Update any other specific data field if you want (must be all capital) without changing the rest of the fields (e.g. only change the FIRST_NAME of a contact).

⊥ : Optional.

Request: 
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
Response: 
{
    "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
Paramter
Type
Description
api_token
string
Your API token. You can find it in your API main page when logged in.
list_uid
string
Audience uid. You can find it on your audiences page when logged in or can be retrieved from your database if you have saved it.
email
string
Contact's email address for identification.
tag
string
Add a tag to existing tags without overwriting, comma separated if multiple and use plus (+) for tags with space.
Request: 
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
Response: 
{
    "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
Paramter
Type
Description
api_token
string
Your API token. You can find it in your API main page when logged in.
email
string
Contact's email address
Request: 
curl -X GET -H "accept:application/json" -G \
    https://api.dynosend.com/api/v1/contacts/email/{email} \
    -d api_token={api_token} \
Response: 
{
    "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
Paramter
Type
Description
api_token
string
Your API token. You can find it in your API main page when logged in.
email
string
Contact's email address
list_uid
string
Audience uid. You can find it on your audiences page when logged in or can be retrieved from your database if you have saved it.
event_name
string
Event name (e.g: account_created, payment_completed ...).
Request: 
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
Response: 
{}

• 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
Paramter
Type
Description
api_token
string
Your API token. You can find it in your API main page when logged in.
email
string
Contact's email address for identification.
list_uid
string
Audience uid. You can find it on your audiences page when logged in or can be retrieved from your database if you have saved it.
Request: 
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}
Response: 
{
    "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
Paramter
Type
Description
api_token
string
Your API token. You can find it in your API main page when logged in.
email
string
Contact's email address for identification.
list_uid
string
Audience uid. You can find it on your audiences page when logged in or can be retrieved from your database if you have saved it.
Request: 
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}
Response: 
{
    "status": 1,
    "message": "Unsubscribed"
}

• Delete a contact

Delete a subscriber from an audience identified by an email for a specific audience.

Parameters
Paramter
Type
Description
api_token
string
Your API token. You can find it in your API main page when logged in.
email
string
Contact's email address for identification.
list_uid
string
Audience uid. You can find it on your audiences page when logged in or can be retrieved from your database if you have saved it.
Request: 
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}
Response: 
{
    "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
Paramter
Type
Description
api_token
string
Your API token. You can find it in your API main page when logged in.
Request: 
curl -X GET -H "accept:application/json" -G \
    https://api.dynosend.com/api/v1/campaigns \
    -d api_token={api_token}
Response: 
[
    {
        "uid":"5fb48ff221b27",
        "name":"My Awesome Campaign",
        "type":"regular",
        "subject":"An Awesome Subject",
        "html":""<!DOCTYPE html>\n<html lang=\"en\">\n..."",
            "plain": "One column layout...",
            "from_email": "marketing@abccorp.com",
            "from_name":"No Reply",
            "reply_to":"support@abccorp.com",
            "status":"new",
            "delivery_at":null,
            "created_at":"2021-11-18 03:07:30",
            "updated_at":"2021-11-18 03:07:41"
    },
    ...
]

• Get campaign details

Get detailed information and statistics of a campaign identified by a uid code.

Parameters
Paramter
Type
Description
api_token
string
Your API token. You can find it in your API main page when logged in.
uid
string
Campaign uid. You can find it on your campaigns page when logged in.
Request: 
curl -X GET -H "accept:application/json" -G \
    https://api.dynosend.com/api/v1/campaigns/{uid} \
    -d api_token={api_token}
Response: 
{
    "campaign": {
        "uid":"5fb48ff221b27",
        "name":"Untitled",
        "audience":"",
        "segment":"",
        "default_subject":null,
        "from_email":"marketing@abccorp.com",
        "from_name":"Marketing Department",
        "status":"new",
        "created_at":"2021-11-18 03:07:30",
        "updated_at":"2021-11-18 03:07:41"
    },
    "statistics": {
        "subscriber_count":0,
        "delivered_rate":0,
        "open_count":0,
        "unique_open_rate":0,
        "unique_open_count":0,
        "click_rate":"",
        "click_per_unique_open":0,
        "click_count":0,
        "abuse_feedback_count":0,
        "last_click":0,
        "last_open":"",
        "bounce_count":0,
        "unsubscribed":0,
        "links":[],
        "top_locations":[],
        "top_open_contacts":[]
    }
}

• Send a campaign

Send a configured campaign (after you create it on your Dynosend account) identified by a uid code.

Parameters
Paramter
Type
Description
api_token
string
Your API token. You can find it in your API main page when logged in.
uid
string
Campaign uid. You can find it on your campaigns page when logged in.
Request: 
curl -X POST -H "accept:application/json" -G \
    https://api.dynosend.com/api/v1/campaigns/{uid}/start \
    -d api_token={api_token}
Response: 
{
    "message": "Campaign started!",
}

• Pause a campaign

Pause a sending campaign identified by a uid code.

Parameters
Paramter
Type
Description
api_token
string
Your API token. You can find it in your API main page when logged in.
uid
string
Campaign uid. You can find it on your campaigns page when logged in.
Request: 
curl -X POST -H "accept:application/json" -G \
    https://api.dynosend.com/api/v1/campaigns/{uid}/pause \
    -d api_token={api_token}
Response: 
{
    "message": "Campaign paused!",
}

• Resume a campaign

Resume a paused campaign identified by a uid code.

Parameters
Paramter
Type
Description
api_token
string
Your API token. You can find it in your API main page when logged in.
uid
string
Campaign uid. You can find it on your campaigns page when logged in.
Request: 
curl -X POST -H "accept:application/json" -G \
    https://api.dynosend.com/api/v1/campaigns/{uid}/resume \
    -d api_token={api_token}
Response: 
{
    "message": "Campaign resumed!",
}