The Email Builder API allows you to retrieve the list of projects, folders, and campaigns of a given project for a given client account, as well as retrieve the HTML markup and media URLs associated with a campaign. Access to this API must be requested from your account manager.
Once access to the API has been granted, you can generate your API key.
Notes on use
The data made available to you originate from your client account.
The Email Builder backend does not have an absolute usage limit in terms of the number of requests. However, it has a frequency limit for queries. For security reasons, the number of requests to the API is limited to 100 per minute. To avoid exceeding this quota, the retrieved data should be cached. In the event of an exceedance, the IP address of the requesting service will be temporarily blocked.
Integration
Obtaining a connection token
To obtain a connection token or access_token to authenticate with the Email Builder API, execute a POST request to the URL:
https://app.dartagnan.io/oauth/v2/token
The header of your request must contain:
CopyContent-Type: application/json
The body of your request must contain the following three parameters in a JSON object:
Copy{
"client_id": "Your Client_id",
"client_secret": "Your client_secret",
"grant_type": "client_credentials"
}
Your client_id and client_secret need to be generated by your administrator as described above.
Copycurl \
-d '{"client_id":"2_21jd0aeanmu8c0kcosgs[...]8kk8ckksk88sg8cw", "client_secret":"3i7wceyn3b284s8k4s0ko[...]0kc8o8s4w8ckwow", "grant_type": "client_credentials"}'
-H "Content-Type: application/json"
-X POST https://app.dartagnan.io/oauth/v2/token
Copy{
"access_token": "ZWYwMzhlMjdmM2NjNzM1YjdjYzVkYzJmMDI0YjUxZTFk[...]4YTAwYjU3ODk1Nw",
"expires_in": 3600,
"token_type": "bearer",
"scope": null
}
The value returned for access_token should then be passed in the header of each request made to the API.
The lifespan of tokens generated is available in the expires_in property (duration expressed in seconds). The lifespan of a token is 1 hour.
Retrieving the list of projects for a client account
To obtain the list of projects for your client account, execute a GET request to the URL:
https://app.dartagnan.io/api/public/projects
Then, in the request body, pass the Authorization parameter set to Bearer followed by your access_token.
Example request body
Copy{
"Authorization": "Bearer ZWYwMzhlMjdmM2NjNzM1Yjdj[...]k1sdfg5949Nw "
}
The access_token variable is an alphanumeric string that is 86 characters long.
Example request
Copycurl \
-H "Authorization: Bearer ZWYwMzhlMjdmM2NjNzM1YjdjYzVkYzJmMDI0YjUxZTFkNT[...]YjU3ODk1Nw"
https://app.dartagnan.io/api/public/projects
Copy[
{
"id": 2,
"name": "Newsletter Bmobile",
"common": false,
"color": "#47d1ff",
"created": "2019-10-08T09:55:56+0000",
"createdBy": {
"id": 1,
"firstname": "Admin",
"lastname": "Istrateur"
}
},
{
"id": 1,
"name": "Espace Commun",
"common": true,
"color": "#001b3c",
"created": "2019-10-07T13:25:05+0000",
"createdBy": {
"id": 1,
"firstname": "Admin",
"lastname": "Istrateur"
}
}
]
Retrieving the list of folders and campaigns for a project
To obtain the list of folders and campaigns for a client account, execute a GET request to this URL:
https://app.dartagnan.io/api/public/projects/{project_id}
Then, replace {project_id} in the URL with the ID (integer) of the project whose hierarchy you want to retrieve. In the header of this request, set the Authorization parameter to Bearer followed by your access_token.
Example header
Copy{
"Authorization": "Bearer ZWYwMzhlMjdmM2NjNzM1Yjdj[...]k1sdfg5949Nw"
}
Copycurl \
-H "Authorization: Bearer ZWYwMzhlMjdmM2NjNzM1Yjdj[...]k1sdfg5949Nw"
https://app.dartagnan.io/api/public/projects/{project_id}
Copy[
{
"id": 2,
"name": "Novembre",
"folders": [],
"campaigns": [
{
"id": 2,
"name": "Version 1",
"previewPath": "2_5582349515d9d5d43cd593.png"
}
]
}
]
To retrieve the HTML markup and media assets of a campaign, execute a GET request to the URL:
https://app.dartagnan.io/api/public/campaigns/{campaign_id}
Then, replace {campaign_id} in the URL with the ID (integer) of a campaign retrieved from the project hierarchy (see above, "Retrieving the list of folders and campaigns for a project").
In the header of this request, set the Authorization parameter to Bearer followed by your access_token.
Example header
Copy{
"Authorization": "Bearer ZWYwMzhlMjdmM2NjNzM1Yjdj[...]k1sdfg5949Nw"
}
Copycurl \
-H "Authorization: Bearer ZWYwMzhlMjdmM2NjNzM1YjdjYzVkYzJmMDI0YjUxZ[...]U3ODk1Nw"
https://app.dartagnan.io/api/public/campaigns/{campaign_id}
Copy{
"html": "<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional //EN...",
"medias": {
"images/1.jpg": "https://app.dartagnan.io/public/.../e8647b59811ed7ea5f2d49435302dc37.jpg",
"images/2.jpg": "https://app.dartagnan.io/public/.../196c843bbfe9beccac40a377aa9944a0.jpg"
}
}
To retrieve the HTML code separated by section and the media assets of a campaign, execute a GET request to the URL:
https://app.dartagnan.io/api/public/campaigns/{campaign_id}/split
Next, add the following parameters:
Allows you to activate or deactivate the encoding of special characters in the texts present in the generated HTML markup.
The values accepted are true (recommended) and false.
Allows you to select the type of encoding to apply to the generated HTML markup.
The values accepted are UTF8 (recommended), ISO88595, and ISO885915.
Allows you to define the HTML string that will be inserted into the campaign template in place of each section. The { sectionName } string will be automatically replaced with the name of the corresponding section. An example for a value:
<span class="droppable" id="{ sectionName }"></span>
The value of the splitPattern string must be encoded for the URL to be syntactically correct (url encode).
Then, replace {campaign_id} in the URL with the ID (integer) of a campaign retrieved from the project hierarchy (see above, "Retrieving the list of folders and campaigns for a project").
In the header of this request, set the Authorization parameter to Bearer followed by your access_token.
Copy{
"Authorization": "Bearer ZWYwMzhlMjdmM2NjNzM1Yjdj[…]k1sdfg5949Nw"
}
Copycurl \
-H "Authorization: Bearer ZWYwMzhlMjdmM2NjNzM1Yjdj[...]k1Nw"
https://app.dartagnan.io/api/public/campaigns/{campaign_id}/split? encode=true&router=UTF8&splitPattern=%3Cspan%20class%3D%22droppable%22%20id%3D%22%7B%20sectionName%20%7D%22%3E%3C%2Fspan%3E
Copy{
"skeleton": "<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional //EN...",
"sections": {
"section1": "<table ...",
"section2": "<table ..."
},
"medias": {
"images/1.jpg": "https://app.dartagnan.io/public/.../e8647b59811ed7ea5f2d49435302dc37.jpg",
"images/2.jpg": "https://app.dartagnan.io/public/.../196c843bbfe9beccac40a377aa9944a0.jpg"
}
}
The section names listed in the sections object correspond to the names defined in the Email Builder’s “Structure” tab when editing the campaign.
If a section does not have a defined name in the Email Builder, its generated UUID is used as the identifier in the sections object and in the HTML markup available in the skeleton property.
For security reasons, the lifespan of the media retrieved through this method is limited. Therefore, you cannot use their URLs for your routing. You need to download and host them yourself.