Introduction to DMDS REST API
With the REST API, we can use the following methods, always under HTTPS (HTTP encrypted with SSL/TLS).
GET to retrieve information
PUT to update new information
POST to update or introduce new information
DEL to delete information
The DMDS (Data Mining and Delivery Services) is a dedicated implementation for each client, meaning that database resources and IP addresses are not shared between clients.
For this, we first need a dmdsid, e.g., empresa1, which is provided by Planisys during the provisioning process. During this process, an APIKEY is also provided, which is a hash sent along with an Authentication header.
Then we can access the web interface with the name dmds-empresa1.planisys.net.
First, the management of Contacts (also called “subscribers”) and Campaigns is distinguished.
Campaigns are created in the web interface, and to be used in the REST API, they must be of type API. There are two other types of campaigns that will not be used in the REST API, which are A/B and Normal.
When an API campaign is created, it is created with a default send. Unlike Normal campaigns, where repetitive sends are scheduled, such as daily/hourly/weekly newsletters, here the send type is one-time.
Warning
Currently, DMDS REST API v1 does not support more than one send within an API campaign, but it will be supported in a future version.
Each time emails are sent through a call, a batch or effective send is created, which will have an effective_send_id returned in the JSON response. For example, if multiple recipients are sent to in one call, all will share the same effective_send_id. You can then query the status of that effective_send_id with a GET along with the events (e.g., which users it was sent to, who and when opened or clicked on the email).
In mail sending calls, we will need a CampNumId or Campaign Numeric Identifier, which can be found in the web interface when clicking on an API campaign.
In calls where a campaign identifier is required, we will use a key-value pair in the JSON as follows, e.g.
"campana_id": 123
Note
Starting from DMDS REST API v2, the campaign number can also be used within a string, e.g., “campaign_id”: “123”, although it must be numeric.
The response to mail sending may contain a 4xx code, for which the user will need to analyze the error (e.g., a missing parameter).
If a send functions correctly, the response is generally a JSON with these 3 pairs:
{"status":"ok", "sent":4, "eeid":"3abc993d-8i88-45e8-a6c9-e879378abba5"}
The uuid returned as eeid (effective_send_id) can be queried later with a GET. The number following sent is the number of emails sent during the call, e.g., one recipient with 3 copies.
Note
The documentation is shown in the CURL section, and then it can be applied to other programming languages.
Concepts
Contact: is an email address with metadata such as first name, last name, gender, also known as a subscriber
Base: is a group or list of contacts, also known as origin
Topic: is an unsubscribe site, meaning a topic from which a contact can unsubscribe
Summary
API Method |
HTTP Supported Methods |
|---|---|
/v1/contact/ |
GET, POST |
v1/contact/unsubscribe/ |
GET, POST |
v1/send/send/ |
GET, POST |
v1/send/send_one_uri/ |
GET, POST |
v1/send/send_many_uri/ |
GET, POST |
v1/send/send_one_inline_xml/ |
GET, POST |
v1/send/send_one_inline_rawtext/ |
GET, POST |
v1/send/send_one_inline/ |
GET, POST |
v1/send/send_one_form/ |
GET, POST |
v1/send/send_one_inline_raw/ |
GET, POST |
v1/send/send_many_inline/ |
GET, POST |
v1/send/ |
GET, POST |
v1/eeid_info/<eeid> |
GET |
v1/global/ |
GET, POST |
v1/campaign/ |
GET, POST |
v1/campaign/results/<id>/<day> |
GET |
v1/group/ |
GET, POST |
v1/base/ |
GET, POST |
v1/contact/ |
GET, POST |
v1/contact/<email> |
GET, POST |
v1/contact_events/<email> |
GET |
v1/sent/<email> |
GET |
v1/sent_items/<email> |
GET |
v1/invalid_contacts/ |
GET |
v1/filters/ |
GET |
v1/fields/ |
GET, POST |
v1/sent_today/ |
GET |
v1/sent_yesterday/ |
GET |
v1/schedule_send/ |
POST |
v1/audiences/ |
GET |
v1/origins/ |
GET |
v1/lists/ |
GET |
v1/groups/ |
GET |
v1/bases/ |
GET |
v1/version/ |
GET |
v1/whitelist/<email> |
GET, POST, PUT, DELETE |
v1/invalidate/<email> |
GET |
v1/revalidate/<email> |
GET |
v1/event_count/ |
GET |
v1/view_events/ |
GET |
Updated on 2024-08-21