API docs by Redocly

Dyspatch API (2023.01)

Download OpenAPI specification:Download

Dyspatch Support: support@dyspatch.io URL: https://docs.dyspatch.io Terms of Service

Introduction

The Dyspatch API is based on the REST paradigm, and features resource based URLs with standard HTTP response codes to indicate errors. We use standard HTTP authentication and request verbs, and all responses are JSON formatted. See our Implementation Guide for more details on how to implement Dyspatch.

API Client Libraries

Dyspatch provides API Clients for popular languages and web frameworks.

Templates

Templates are the email templates found in your Dyspatch account. Only the published Template Draft is returned. A typical integration will start with using the Templates list endpoint to iterate through and sync Templates.

List Templates

Gets a list of Template Metadata objects for all templates. Up to 25 results returned before results are paginated.

Authorizations:
Bearer
query Parameters
cursor
string

A cursor value used to retrieve a specific page from a paginated result set.

header Parameters
Accept
required
string

A version of the API that should be used for the request. For example, to use version "2023.01", set the value to "application/vnd.dyspatch.2023.01+json"

Responses

Response samples

Content type
application/vnd.dyspatch.2023.01+json
{
  • "cursor": {
    },
  • "data": [
    ]
}

Get Template by ID

Gets a template object with the matching ID. Templates without a published draft will result in an error.

Authorizations:
Bearer
path Parameters
templateId
required
string

A template ID

query Parameters
targetLanguage
required
string
Enum: "html" "handlebars" "ampscript" "freemarker" "cheetah" "jinja" "liquid" "mandrillhandlebars"

The type of templating language to compile as. Should only be used for visual templates.

header Parameters
Accept
required
string

A version of the API that should be used for the request. For example, to use version "2023.01", set the value to "application/vnd.dyspatch.2023.01+json"

Responses

Response samples

Content type
application/vnd.dyspatch.2023.01+json
{
  • "id": "tem_g3L7Cw6Hp5wU",
  • "name": "Template Name",
  • "description": "Description of Template",
  • "url": "/templates/tem_g3L7Cw6Hp5wUaf395LehwK",
  • "compiled": {
    },
  • "path": "fdr_01gb8vd6pz/fdr_01gqjmdbq/fdr_01gqjmg1",
  • "workspaceId": "fdr_01gb8vd6pz",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "publishedDraftId": "tdft_g3L7Cw6Hp5wU",
  • "localizations": [
    ]
}

Drafts

Drafts represent unpublished versions of templates that are still mutable. There could be many in progress drafts for a template.

List Drafts

Returns all drafts for your organization.

Authorizations:
Bearer
query Parameters
cursor
string

A cursor value used to retrieve a specific page from a paginated result set.

status
string
Value: "awaitingTranslation"

Filter the list of drafts by a particular status

header Parameters
Accept
required
string

A version of the API that should be used for the request. For example, to use version "2023.01", set the value to "application/vnd.dyspatch.2023.01+json"

Responses

Response samples

Content type
application/vnd.dyspatch.2023.01+json
{
  • "cursor": {
    },
  • "data": [
    ]
}

Submit the draft for approval

Moves the draft into submitted state.

Authorizations:
Bearer
path Parameters
draftId
required
string

A draft ID

header Parameters
Accept
required
string

A version of the API that should be used for the request. For example, to use version "2023.01", set the value to "application/vnd.dyspatch.2023.01+json"

Responses

Get Draft by ID

Gets a draft object with the matching ID. The "compiled" field will contain the template in the default, unlocalized form.

Authorizations:
Bearer
path Parameters
draftId
required
string

A draft ID

query Parameters
targetLanguage
required
string
Enum: "html" "handlebars" "ampscript" "freemarker" "cheetah" "jinja" "liquid" "mandrillhandlebars"

The type of templating language to compile as. Should only be used for visual templates.

header Parameters
Accept
required
string

A version of the API that should be used for the request. For example, to use version "2023.01", set the value to "application/vnd.dyspatch.2023.01+json"

Responses

Response samples

Content type
application/vnd.dyspatch.2023.01+json
{
  • "id": "tdft_g3L7Cw6Hp5wU",
  • "template": "tem_g3L7Cw6Hp5wU",
  • "name": "Draft Name",
  • "url": "/drafts/tdft_g3L7Cw6Hp5wUaf395LehwK/dft_g3L7Cw6Hp5wU",
  • "path": "fdr_01gb8vd6pz/fdr_01gqjmdbq/fdr_01gqjmg1",
  • "workspaceId": "fdr_01gb8vd6pz",
  • "compiled": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "localizations": [
    ],
  • "status": "LOCKED_FOR_TRANSLATION",
  • "templateName": "Template Name"
}

Get localizations on a draft

Returns localization metadata for the draft

Authorizations:
Bearer
path Parameters
draftId
required
string

A draft ID

header Parameters
Accept
required
string

A version of the API that should be used for the request. For example, to use version "2023.01", set the value to "application/vnd.dyspatch.2023.01+json"

Responses

Response samples

Content type
application/vnd.dyspatch.2023.01+json
[
  • {
    }
]

Create or update a localization

Inserts a localization or sets the name on an existing localization that already uses the languageId

Authorizations:
Bearer
path Parameters
draftId
required
string

A draft ID

languageId
required
string

A language ID (eg: en-US)

header Parameters
Accept
required
string

A version of the API that should be used for the request. For example, to use version "2023.01", set the value to "application/vnd.dyspatch.2023.01+json"

Request Body schema: application/json
required
name
string

Responses

Request samples

Content type
application/json
{
  • "name": "English (US)"
}

Remove a localization

Deletes the localization with the given language ID if it exists

Authorizations:
Bearer
path Parameters
draftId
required
string

A draft ID

languageId
required
string

A language ID (eg: en-US)

header Parameters
Accept
required
string

A version of the API that should be used for the request. For example, to use version "2023.01", set the value to "application/vnd.dyspatch.2023.01+json"

Responses

Set translations for language

Completely replaces any existing translations for the given language with those provided in request body. Variables embedded in keys or values are expected to be in the format %(my_variable)s and will automatically convert to the correct Dyspatch format depending on the type of template. Accepts key/value pairs in JSON format or in gettext PO file format. For JSON set Content-Type header to application/json. For gettext PO format set Content-Type header to text/x-gettext-translation.

Authorizations:
Bearer
path Parameters
draftId
required
string

A draft ID

languageId
required
string

A language ID (eg: en-US)

header Parameters
Accept
required
string

A version of the API that should be used for the request. For example, to use version "2023.01", set the value to "application/vnd.dyspatch.2023.01+json"

Request Body schema: application/json
required
property name*
additional property
string

Responses

Request samples

Content type
application/json
{
  • "Hello %(name)s": "Bonjour %(name)s",
  • "Welcome": "Bienvenue"
}

Get localization keys

Returns the list of values that need to be translated for the draft. Set the Accept header to application/vnd.dyspatch.2023.01+json to get a JSON object, or text/vnd.dyspatch.2023.01+x-gettext-translation to get the POT file.

Authorizations:
Bearer
path Parameters
draftId
required
string

A draft ID

header Parameters
Accept
required
string

A version of the API that should be used for the request. For example, to use version "2023.01", set the value to "application/vnd.dyspatch.2023.01+json"

Responses

Response samples

Content type
[
  • {
    }
]

Localizations

Localization objects are the same as Template objects except they contain localized content. If your account is using localizations then use this instead of the compiled Template object.

Get Localization Object by ID

Returns the published content associated with the localization of the matching ID

Authorizations:
Bearer
path Parameters
localizationId
required
string

A localization ID

query Parameters
targetLanguage
required
string
Enum: "html" "handlebars" "ampscript" "freemarker" "cheetah" "jinja" "liquid" "mandrillhandlebars"

The type of templating language to compile as. Should only be used for visual templates.

header Parameters
Accept
required
string

A version of the API that should be used for the request. For example, to use version "2023.01", set the value to "application/vnd.dyspatch.2023.01+json"

Responses

Response samples

Content type
application/vnd.dyspatch.2023.01+json
{
  • "id": "loc_g3L7Cw6Hp5wUaf395LehwK",
  • "languages": [
    ],
  • "url": "/localizations/loc_g3L7Cw6Hp5wUaf395LehwK",
  • "template": "tem_g3L7Cw6Hp5wU",
  • "compiled": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "name": "English (US)",
  • "localeGroup": "lgr_alka38ajla301"
}

Get Draft Localization Object by ID

Returns a specific localization object of the matching draft with a matching localization ID

Authorizations:
Bearer
path Parameters
draftId
required
string

A draft ID

localizationId
required
string

A localization ID

query Parameters
targetLanguage
required
string
Enum: "html" "handlebars" "ampscript" "freemarker" "cheetah" "jinja" "liquid" "mandrillhandlebars"

The type of templating language to compile as. Should only be used for visual templates.

header Parameters
Accept
required
string

A version of the API that should be used for the request. For example, to use version "2023.01", set the value to "application/vnd.dyspatch.2023.01+json"

Responses

Response samples

Content type
application/vnd.dyspatch.2023.01+json
{
  • "id": "loc_g3L7Cw6Hp5wUaf395LehwK",
  • "languages": [
    ],
  • "url": "/localizations/loc_g3L7Cw6Hp5wUaf395LehwK",
  • "template": "tem_g3L7Cw6Hp5wU",
  • "compiled": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "name": "English (US)",
  • "localeGroup": "lgr_alka38ajla301"
}

Workspaces

List Workspaces

Gets a list of Workspace objects for all workspaces. Up to 25 results returned before results are paginated.

Authorizations:
Bearer
query Parameters
cursor
string

A cursor value used to retrieve a specific page from a paginated result set.

header Parameters
Accept
required
string

A version of the API that should be used for the request. For example, to use version "2023.01", set the value to "application/vnd.dyspatch.2023.01+json"

Responses

Response samples

Content type
application/vnd.dyspatch.2023.01+json
{
  • "cursor": {
    },
  • "data": [
    ]
}

List Folder

Gets a Folder with a list of its sub-folders for the provided id.

Authorizations:
Bearer
path Parameters
folderId
required
string

A workspace/folder ID

header Parameters
Accept
required
string

A version of the API that should be used for the request. For example, to use version "2023.01", set the value to "application/vnd.dyspatch.2023.01+json"

Responses

Response samples

Content type
application/vnd.dyspatch.2023.01+json
{
  • "id": "fdr_01g0z4d5aw",
  • "name": "Name of Folder",
  • "description": "Description of Folder",
  • "url": "/workspaces/fdr_g3L7Cw6Hp5wUaf395LehwK",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "subfolders": [
    ]
}