Dynosend Developer Documentation

Introduction

The Dynosend API (version 2.0) 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 URL and authentication key.

Authentication

Our 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

Rate limit

All Dynosend's API endpoints are limited to 10 requests per user every second.

Response codes

This is an overview of the response codes you might see from our API.

Status code	Description
200	Successful request returns the requested data
204	Successful request returns an empty response
400	Cause: Some data is missing to perform the requestSolution: Read the response message to know what data is missing
401	Cause: Invalid authenticationSolution: Make sure your API key is correct
401	Cause: You are not authorized to access this resourceSolution: Contact your account administrator or read the returned message
401	Cause: You have reached your monthly quotaSolution: Upgrade your account or wait until your usage resets
404	Cause: Requested resource does not existSolution: Double check the requested resource exists or create it
405	Cause: Method is not allowed for this endpointSolution: Read the documentation to use the right method for each endpoint
429	Cause: You are sending too many requests quicklySolution: Pace your requests
500	Cause: Issue on our serversSolution: Retry your request after some time while we investigate the issue
503	Cause: Our servers are experiencing high trafficSolution: Please retry your requests after some time

Audiences

An audience is a separate list where you can store your customer data. Each audience has its own segments, custom fields and unique contacts. Having multiple audiences is useful if you are managing multiple businesses or sources of data, for example you can have an audience for your customers and another audience for blog subscribers.

List audiences

Returns a list of your audiences and their basic information

Parameters

None...

Request:

curl -X GET "https://api.dynosend.com/api/v2/audiences" \

 -H "Content-Type: application/json" \

 -H "Authorization: Bearer YOUR_API_TOKEN"

$client = new \DynosendSDK\Client('YOUR_API_TOKEN');

$client->audience()->getAll();

Response:

[
	{
		"id": 16,
		"uid": "5fade5c93e42a",
		"name": "SaaS customers",
		"default_subject": "An Awesome Subject",
		"from_email": "support@abccorp.com",
		"from_name": "Company",
		"created_at": "2021-12-04T07:29:24.000000Z",
		"updated_at": "2021-12-04T07:29:24.000000Z"
	}
  ]

Get an audience

Returns the information of an audience identified by the given audience_uid

Parameters

Stringaudience_uid

Required

Each audience has its unique UID that can be found in your account or can be retrieved with the "List audiences" API endpoint.

Request:

curl -X GET "https://api.dynosend.com/api/v2/audiences" \

 -H "Content-Type: application/json" \

 -H "Authorization: Bearer YOUR_API_TOKEN" \

 -d '{"audience_uid": "YOUR_AUDIENCE_UID"}'

Response:

{
	"audience": {
		"id": 16,
		"uid": "5fade5c93e42a",
		"name": "SaaS customers",
		"default_subject": "An Awesome Subject",
		"from_email": "support@abccorp.com",
		"from_name": "Company",
		"created_at": "2021-12-04T07:29:24.000000Z",
		"updated_at": "2021-12-04T07:29:24.000000Z",
		"fields": [
			{
				"label": "Email",
				"type": "text",
				"tag": "EMAIL",
				"visibe": true,
				"required": true,
			},
		]
	},
	"contact_information": {
		"company": "ACME Corp",
		"address_1": "578 Hudson Hills",
		"address_2": "Apt. 909",
		"country": "United States",
		"state": "Nevada",
		"zip": "52441-9913",
		"city": "Greenland",
		"phone": "+14803795457",
		"website": "https://company.com",
		"email": "contact@company.com"	
	},
	"statistics": {
		"contact_count": 1420,
		"subscribe_rate": 0.98,
		"unsubscribe_rate": 0.2,
		"subscribe_count": 28,
		"unsubscribe_count": 28
	}
  }

Create a custom field

Beside the defaul email field, you can add custom fields to your audiences to store more information about your customers such as their preferences, plan names, privacy consents etc. Currently the only field types allowed in this API are text, number and datetime.

Parameters

Stringaudience_uid	Required	Each audience has its unique UID that can be found in your account or can be retrieved with the "List audiences" API endpoint.
Stringtype	Required	Choose one of these types: text, number, textarea, date, datetime, time.
Stringlabel	Required	Custom field label, visible on your dashboard, pages and embedded form.
Stringtag	Required	A unique name used to identify a custom field and can also be used for liquid tags when sending an email. All capital and may contain underscores.

Request:

curl -X POST "https://api.dynosend.com/api/v2/audiences/add-field" \

 -H "Content-Type: application/json" \

 -H "Authorization: Bearer YOUR_API_TOKEN" \

 -d '
	{
	  "audience_uid": "YOUR_AUDIENCE_UID",
	  "type": "text",
	  "label": "Plan name",
	  "tag": "PLAN_NAME",
   }'

Response:

{
	"status": "success",
	"message": "Custom field created",
  }

Contacts

A contact or often referred to as subscriber is a unique email in a specific audience.

List contacts

Returns a list of contacts in a given audience

Parameters

Stringaudience_uid	Required	Each audience has its unique UID that can be found in your account or can be retrieved with the "List audiences" API endpoint.
Integerpage	Optional	Page number if you choose to paginate your contacts instead of listing all of them.
Integerper_page	Optional	Number of contacts per page, 20 by default if not specified.

Request:

curl -X GET "https://api.dynosend.com/api/v2/contacts" \

 -H "Content-Type: application/json" \

 -H "Authorization: Bearer YOUR_API_TOKEN" \

 -d '{"audience_uid": "YOUR_AUDIENCE_UID"}'

Response:

[
	{
		"id": 682,
		"contact_uid": "6550142203654",
		"email": "jake@gmail.com",
		"status": "subscribed",
		"source": "api",
		"ip_address": "171.22.152.19",
		"tags": "subscribed,newcustomer",
		"created_at": "2021-12-04T07:29:24.000000Z",
		"updated_at": "2021-12-04T07:29:24.000000Z",
		"PLAN_NAME": "Standard"
	},
	{
		"id": 683,
		"contact_uid": "6336502260525",
		"email": "finn@gmail.com",
		"status": "unconfirmed",
		"source": "api",
		"ip_address": "82.44.87.200",
		"tags": "unconfirmed",
		"created_at": "2021-12-04T07:29:24.000000Z",
		"updated_at": "2021-12-04T07:29:24.000000Z",
		"PLAN_NAME": "Premium"
	}
  ]

Create a contact

Add a contact to a given audience. An error will be returned if an existing contact is found with the same email, and the subscription status will either be subscribed or unconfirmed depending on double opt-in settings.

Parameters

Stringaudience_uid	Required	Each audience has its unique UID that can be found in your account or can be retrieved with the "List audiences" API endpoint.
StringEMAIL	Required	Your new contact's email address.
Stringtag	Optional	Comma separated list if multiple (e.g. subscriber, purchaser ...etc). Tags can be used for segments or triggering automations.
Booleanignore_doi	Optional	Ignore double opt-in settings to immediately subscribe the new contact without sending a confirmation email.

Request:

curl -X POST "https://api.dynosend.com/api/v2/contacts" \

 -H "Content-Type: application/json" \

 -H "Authorization: Bearer YOUR_API_TOKEN" \

 -d '
	{
	  "audience_uid": "YOUR_AUDIENCE_UID",
	  "EMAIL": "jake@gmail.com",
	  "CUSTOM_FIELD_TAG": "custom field value"  // optional
   }'

$client = new \DynosendSDK\Client('YOUR_API_TOKEN');

$client->contact()->create([

    'audience_uid' => 'YOUR_AUDIENCE_UID',

    'EMAIL' => 'jake@gmail.com',

    'CUSTOM_FIELD_TAG' => 'custom field value'

]);

Response:

{
	"status": "success",
	"message": "Contact created",
	"contact_uid": "6550142203654",
  }

Get a contact

Get a contact from a given audience.

Parameters

Stringaudience_uid	Required	Each audience has its unique UID that can be found in your account or can be retrieved with the "List audiences" API endpoint.
Stringcontact_uid	Recommended	The UID of the contact you want to get.
Stringemail	Optional	Your contact's email address if you choose to not use identification by contact_uid.

Request:

curl -X GET "https://api.dynosend.com/api/v2/contacts" \

 -H "Content-Type: application/json" \

 -H "Authorization: Bearer YOUR_API_TOKEN" \

 -d '
	{
	  "audience_uid": "YOUR_AUDIENCE_UID",
	  "contact_uid": "YOUR_CONTACT_UID"
   }'

Response:

{
	"contact": {
		"id": 682,
		"contact_uid": "6550142203654",
		"email": "jake@gmail.com",
		"status": "subscribed",
		"source": "api",
		"ip_address": "171.22.152.19",
		"tags": "subscribed,newcustomer",
		"created_at": "2021-12-04T07:29:24.000000Z",
		"updated_at": "2021-12-04T07:29:24.000000Z",
		"PLAN_NAME": "Standard"
	}
  }

Get a duplicate contact

Search for duplicate contacts across all audiences.

Parameters

Stringemail

Required

The email address of the contact(s) you're looking for

Request:

curl -X GET "https://api.dynosend.com/api/v2/contacts/duplicate" \

 -H "Content-Type: application/json" \

 -H "Authorization: Bearer YOUR_API_TOKEN" \

 -d '{"email": "YOUR_EMAIL"}'

Response:

{
	"contacts": [
		{
			"id": 682,
			"contact_uid": "6550142203654",
			"audience_uid": "5fade5c93e42a",
			"email": "jake@gmail.com",
			"status": "subscribed",
			"source": "api",
			"ip_address": "171.22.152.19",
			"tags": "subscribed,newcustomer",
			"created_at": "2021-12-04T07:29:24.000000Z",
			"updated_at": "2021-12-04T07:29:24.000000Z",
			"PLAN_NAME": "Standard"
		},
		{
			"id": 856,
			"contact_uid": "1536051260598",
			"audience_uid": "5dfwf9u101490",
			"email": "jake@gmail.com",
			"status": "unsubscribed",
			"source": "api",
			"ip_address": "74.123.43.192",
			"tags": "unsubscribed",
			"created_at": "2024-01-06T12:16:05.000000Z",
			"updated_at": "2024-01-06T12:16:05.000000Z",
			"FIRST_NAME": "Jake"
		}
	 ]
  }

Update a contact

Update a contact's email address and/or custom field data.

Parameters

Stringaudience_uid	Required	Each audience has its unique UID that can be found in your account or can be retrieved with the "List audiences" API endpoint.
Stringcontact_uid	Recommended	The UID of the contact you want to update.
Stringemail	Optional	Your contact's email address if you choose to not use identification by contact_uid.
Stringnew_email	Optional	The updated email address of your contact if you choose to change it.
Stringtag	Optional	This removes all existing tags and replace them with new ones. Use "Tag a contact" endpoint instead if you just want to add more tags.

Request:

curl -X PATCH "https://api.dynosend.com/api/v2/contacts/update" \

 -H "Content-Type: application/json" \

 -H "Authorization: Bearer YOUR_API_TOKEN" \

 -d '
	{
	  "audience_uid": "YOUR_AUDIENCE_UID",
	  "contact_uid": "YOUR_CONTACT_UID",
	  "new_email": "newemail@gmail.com",
	  "tag": "updated, new user",
	  "CUSTOM_FIELD_TAG": "custom field value"
   }'

$client = new \DynosendSDK\Client('YOUR_API_TOKEN');

$client->contact()->update([

    'audience_uid' => 'YOUR_AUDIENCE_UID',

    'contact_uid' => 'YOUR_CONTACT_UID',

    'new_email' => 'new_jake@gmail.com',

    'tag' => 'new tags',

    'CUSTOM_FIELD_TAG' => 'custom field value'

]);

Response:

{
	"status": "success",
	"message": "Contact updated",
	"contact_uid": "6550142203654",
  }

Tag a contact

Add new tags to an existing contact in an audience.

Parameters

Stringaudience_uid	Required	Each audience has its unique UID that can be found in your account or can be retrieved with the "List audiences" API endpoint.
Stringcontact_uid	Recommended	The UID of the contact you want to tag.
Stringemail	Optional	Your contact's email address if you choose to not use identification by contact_uid.
Stringtag	Required	New tags will be added and existing ones will not be affected.

Request:

curl -X PATCH "https://api.dynosend.com/api/v2/contacts/addtag" \

 -H "Content-Type: application/json" \

 -H "Authorization: Bearer YOUR_API_TOKEN" \

 -d '
	{
	  "audience_uid": "YOUR_AUDIENCE_UID",
	  "contact_uid": "YOUR_CONTACT_UID",
	  "tag": "added tag"
   }'

Response:

{
	"status": "success",
	"message": "Tag added",
  }

Subscribe a contact

Change the subscription status of a contact to Subscribed to receive future messages.

Parameters

Stringaudience_uid	Required	Each audience has its unique UID that can be found in your account or can be retrieved with the "List audiences" API endpoint.
Stringcontact_uid	Recommended	The UID of the contact you want to change their status.
Stringemail	Optional	Your contact's email address if you choose to not use identification by contact_uid.

Request:

curl -X PATCH "https://api.dynosend.com/api/v2/contacts/subscribe" \

 -H "Content-Type: application/json" \

 -H "Authorization: Bearer YOUR_API_TOKEN" \

 -d '
	{
	  "audience_uid": "YOUR_AUDIENCE_UID",
	  "contact_uid": "YOUR_CONTACT_UID"
   }'

Response:

{
	"status": "success",
	"message": "Contact subscribed",
  }

Unsubscribe a contact

Change the subscription status of a contact to Unsubscribed to no longer receive future messages.

Parameters

Stringaudience_uid	Required	Each audience has its unique UID that can be found in your account or can be retrieved with the "List audiences" API endpoint.
Stringcontact_uid	Recommended	The UID of the contact you want to change their status.
Stringemail	Optional	Your contact's email address if you choose to not use identification by contact_uid.

Request:

curl -X PATCH "https://api.dynosend.com/api/v2/contacts/unsubscribe" \

 -H "Content-Type: application/json" \

 -H "Authorization: Bearer YOUR_API_TOKEN" \

 -d '
	{
	  "audience_uid": "YOUR_AUDIENCE_UID",
	  "contact_uid": "YOUR_CONTACT_UID"
   }'

Response:

{
	"status": "success",
	"message": "Contact unsubscribed",
  }

Send an event

Send an event from your own application whenever a customer does something, e.g. starts_trial

Parameters

Stringaudience_uid	Required	Each audience has its unique UID that can be found in your account or can be retrieved with the "List audiences" API endpoint.
Stringcontact_uid	Recommended	The UID of the contact you want to send the event for.
Stringevent_name	Required	The event you want to send, only letters and numbers, no spaces or special letters are allowed. (e.g: account_created, payment_completed ...)
Stringemail	Optional	Your contact's email address if you choose to not use identification by contact_uid.

Request:

curl -X POST "https://api.dynosend.com/api/v2/events" \

 -H "Content-Type: application/json" \

 -H "Authorization: Bearer YOUR_API_TOKEN" \

 -d '
	{
	  "audience_uid": "YOUR_AUDIENCE_UID",
	  "contact_uid": "YOUR_CONTACT_UID",
	  "event_name": "YOUR_EVENT"
   }'

$client = new \DynosendSDK\Client('YOUR_API_TOKEN');

$client->event()->sendevent([

    'audience_uid' => 'YOUR_AUDIENCE_UID',

    'contact_uid' => 'YOUR_CONTACT_UID',

    'event_name' => 'account_created'

]);

Response:

A successful request returns an empty response

Delete a contact

Permanently delete a contact from your audience (best for compliance with GDPR and CCPA).

Parameters

Stringaudience_uid	Required	Each audience has its unique UID that can be found in your account or can be retrieved with the "List audiences" API endpoint.
Stringcontact_uid	Recommended	The UID of the contact you want to delete.
Stringemail	Optional	Your contact's email address if you choose to not use identification by contact_uid.

Request:

curl -X DELETE "https://api.dynosend.com/api/v2/contacts" \

 -H "Content-Type: application/json" \

 -H "Authorization: Bearer YOUR_API_TOKEN" \

 -d '
	{
	  "audience_uid": "YOUR_AUDIENCE_UID",
	  "contact_uid": "YOUR_CONTACT_UID"
   }'

Response:

{
	"status": "success",
	"message": "Contact deleted",
  }

Campaigns

This endpoint can be used to interact with campaign or sometimes referred to as broadcast campaigns, you may view all and any of your campaigns' information or perform certain actions such us sending, pausing and resuming campaigns.

List campaign

Returns a list of your campaigns and their basic information

Parameters

None...

Request:

curl -X GET "https://api.dynosend.com/api/v2/campaigns" \

 -H "Content-Type: application/json" \

 -H "Authorization: Bearer YOUR_API_TOKEN"

Response:

[
	{
		"uid": "66008ks0512la",
		"name": "Monthly update",
		"type": "regular",
		"subject": "This month's product update",
		"from_email": "team@acme.com",
		"from_name": "Acme",
		"reply_to": "team@acme.com",
		"status": "done",
		"delivered_at": "2024-04-17T22:05:11.000000Z",
		"created_at": "2024-04-17T21:12:16.000000Z",
		"updated_at": "2024-04-17T20:07:45.000000Z"
	}
  ]

Get a campaign

Returns an individual campaign and its information.

Parameters

Stringcampaign_uid

Required

Campaign UID can be found in your account's campaign list or can be retrieved with the "List campaigns" API endpoint.

Request:

curl -X GET "https://api.dynosend.com/api/v2/campaigns" \

 -H "Content-Type: application/json" \

 -H "Authorization: Bearer YOUR_API_TOKEN" \

 -d '{"campaign_uid": "YOUR_CAMPGIN_UID"}'

Response:

{
	"campaign": {
		"uid": "66008ks0512la",
		"name": "Monthly update",
		"type": "regular",
		"subject": "This month's product update",
		"from_email": "team@acme.com",
		"from_name": "Acme",
		"reply_to": "team@acme.com",
		"status": "done",
		"delivered_at": "2024-04-17T22:05:11.000000Z",
		"created_at": "2024-04-17T21:12:16.000000Z",
		"updated_at": "2024-04-17T20:07:45.000000Z"
	},
	"insights": {
		"recipients": 123,
		"delivery_rate": 0.95, # 95% 
		"open_count": 31,
		"unique_open_count": 21,
		"unique_open_rate": 0.25,
		"click_count": 16,
		"unique_click_count": 9,
		"click_rate": 0.19,
		"click_per_unique_open": 0.42,
		"spam_report_count": 0,
		"spam_report_rate": 0,
		"bounce_count": 1,
		"bounce_rate": 0.01,
		"unsubscribed_count": 0,
		"unsubscribed_rate": 0,
	 }
  }

Start a campaign

Start sending a ready broadcast campaign.

Parameters

Stringcampaign_uid

Required

Campaign UID can be found in your account's campaign list or can be retrieved with the "List campaigns" API endpoint.

Request:

curl -X POST "https://api.dynosend.com/api/v2/campaigns/start" \

 -H "Content-Type: application/json" \

 -H "Authorization: Bearer YOUR_API_TOKEN" \

 -d '{"campaign_uid": "YOUR_CAMPGIN_UID"}'

Response:

{
	"status": "success",
	"message": "Campaign started",
  }

Pause a campaign

Pause a sending broadcast campaign.

Parameters

Stringcampaign_uid

Required

Campaign UID can be found in your account's campaign list or can be retrieved with the "List campaigns" API endpoint.

Request:

curl -X POST "https://api.dynosend.com/api/v2/campaigns/pause" \

 -H "Content-Type: application/json" \

 -H "Authorization: Bearer YOUR_API_TOKEN" \

 -d '{"campaign_uid": "YOUR_CAMPGIN_UID"}'

Response:

{
	"status": "success",
	"message": "Campaign paused",
  }

Resume a campaign

Resume a paused broadcast campaign.

Parameters

Stringcampaign_uid

Required

Campaign UID can be found in your account's campaign list or can be retrieved with the "List campaigns" API endpoint.

Request:

curl -X POST "https://api.dynosend.com/api/v2/campaigns/resume" \

 -H "Content-Type: application/json" \

 -H "Authorization: Bearer YOUR_API_TOKEN" \

 -d '{"campaign_uid": "YOUR_CAMPGIN_UID"}'

Response:

{
	"status": "success",
	"message": "Campaign resumed",
  }

Transactional messages

Transactional messages are personalized communications sent in response to specific actions or events, such as order confirmations or password resets. They provide timely information about transactions or account activities, focusing on service rather than promotion.

Send a message

Send a configured transactional message to an existing or new contact.

Main parameters

Stringrecipient	Required	The valid email address of your recipient. If no matching contact exists in your audience, a new contact will be created using the provided email.
Stringtransactional_uid	Required	Your transactional message UID.
Stringsubject	Optional	You may specify a subject for each message to override the configured one.
ArraycustomHeaders	Optional	Custom headers that can be added to your email. This is a list of headers you cannot use.

Internal content parameters

These parameters can only be included when the content setting of your message is set to Internal.

ArraycustomTags

Optional

Personalization tags that can contain data sent from your message.

External content parameters

These parameters can only be included when the content setting of your message is set to External.

StringhtmlBody	Required	The HTML code of your message's content.
StringtextBody	Required	The Text version of your message's content.

Request:

curl -X POST "https://api.dynosend.com/api/v2/transactional" \

 -H "Content-Type: application/json" \

 -H "Authorization: Bearer YOUR_API_TOKEN" \

 -d '
	{
	  "recipient": "RECIPIENT_EMAIL",
	  "transactional_uid": "MESSAGE_UID",
	  "textBody": "This is the text version",
	  "htmlBody": "<html>This is the Html version</html>",
	  "customTags": [
	  	  {
	  	  	  "Name": "PASSWORD_LINK",
	  	  	  "Value": "https://app.company.com/reset/ea4a45d4a8fqiai"
	  	  },
	  	  {
	  	  	  "Name": "RESET_TOKEN",
	  	  	  "Value": "ea4a45d4a8fqiai"
	  	  }
	  ],
	  "customHeaders": [
	  	  {
	  	  	  "Name": "X-Header-Name",
	  	  	  "Value": "Header value"
	  	  },
	  	  {
	  	  	  "Name": "X-Header-Name-2",
	  	  	  "Value": "Header value 2"
	  	  }
	  ]
   }'

$client = new \DynosendSDK\Client('YOUR_API_TOKEN');

$client->transactional()->sendmessage([

    'recipient' => 'RECIPIENT_EMAIL',

    'transactional_uid' => 'MESSAGE_UID',

    'textBody' => 'This is the text version',

    'htmlBody' => '<html>This is the Html version</html>',

    'customTags' => [

            'Name' => 'PASSWORD_LINK',

            'Value' => 'https://app.company.com/reset/ea4a45d4a8fqiai',

],

            'Name' => 'RESET_TOKEN',

            'Value' => 'ea4a45d4a8fqiai',

],

    'customHeaders' => [

            'Name' => 'X-Header-Name',

            'Value' => 'Header value',

],

            'Name' => 'X-Header-Name-2',

            'Value' => 'Header value 2',

]);

Response:

{
	"status": "success",
	"message": "Your message has been sent",
	"sending_time": 1713802930
  }

Blacklist

A blacklist is a list of contacts that you don't want to receive your emails.

Check a contact

Checks if your email is blacklisted and returns a boolean of true or false.

Parameters

Stringemail

Required

The email address you want to check.

Request:

curl -X POST "https://api.dynosend.com/api/v2/blacklist" \

 -H "Content-Type: application/json" \

 -H "Authorization: Bearer YOUR_API_TOKEN" \

 -d '{"email": "bademail@gmail.com"}'

Response:

{
	"status": "success",
	"email": "bademail@gmail.com",
	"blacklisted": true,
	"blacklist_time": "2024-02-02T12:16:05.000000Z",
	"reason": "bounced"
  }

Add to blacklist

Add an email to the blacklist to no longer receive your email communications.

Parameters

Stringemail

Required

The email address you want to blacklist.

Request:

curl -X POST "https://api.dynosend.com/api/v2/blacklist/add" \

 -H "Content-Type: application/json" \

 -H "Authorization: Bearer YOUR_API_TOKEN" \

 -d '{"email": "bademail@gmail.com"}'

Response:

A successful request returns an empty response