Documentation Powered by ReDoc

Dyspatch API (2023.07)

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.

Authentication

Bearer

Set Bearer followed by your API key as the Authorization header in your API requests.

Authorization: Bearer EXAMPLEAPIKEYXXXXXXXX12345678

Below is an example curl request with an API key in the Authorization header.

curl --request GET \
--url https://api.dyspatch.io/templates \
--header 'Authorization: Bearer EXAMPLEAPIKEYXXXXXXXX12345678' \
--header 'Accept: application/vnd.dyspatch.2023.03+json'
Security Scheme Type API Key
Header parameter name: Authorization

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.03", set the value to "application/vnd.dyspatch.2023.03+json"

Responses

200

A list of templates

400

Invalid request

401

Unauthenticated

403

Unauthorized

429

Rate limit exceeded

500

Server error

default

Server error

get/templates
https://api.dyspatch.io/templates

Response samples

Content type
application/vnd.dyspatch.2023.03+json
Copy
 Expand all Collapse all
{
  • "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.03", set the value to "application/vnd.dyspatch.2023.03+json"

Responses

200

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

400

Invalid request

401

Unauthenticated

403

Unauthorized

404

Resource not found

429

Rate limit exceeded

500

Server error

default

Server error

get/templates/{templateId}
https://api.dyspatch.io/templates/{templateId}

Response samples

Content type
application/vnd.dyspatch.2023.03+json
Copy
 Expand all Collapse all
{
  • "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": "2024-11-25T21:32:36Z",
  • "updatedAt": "2024-11-25T21:32:36Z",
  • "publishedDraftId": "tdft_g3L7Cw6Hp5wU",
  • "localizations":
    [
    ]
}

Render Template by ID

Renders a template into HTML using the provided data.

Authorizations:
Bearer
path Parameters
templateId
required
string

A template ID

header Parameters
Accept
required
string

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

Responses

200

Rendered template contents incorporating the data passed in the request body.

400

Invalid request

401

Unauthenticated

403

Unauthorized

404

Resource not found

429

Rate limit exceeded

500

Server error

default

Server error

post/render/template/{templateId}
https://api.dyspatch.io/render/template/{templateId}

Response samples

Content type
application/vnd.dyspatch.2023.03+json
Copy
 Expand all Collapse all
{
  • "html": "<html>Hello, world!<html>",
  • "ampHtml": "<html ⚡4email>Hello, world!<html>",
  • "text": "Hello, world!",
  • "subject": "Email Subject Line",
  • "sender": "example@example.com",
  • "replyTo": "example@example.com"
}

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.03", set the value to "application/vnd.dyspatch.2023.03+json"

Responses

200

Drafts

400

Invalid request

401

Unauthenticated

403

Unauthorized

404

Resource not found

429

Rate limit exceeded

500

Server error

default

Server error

get/drafts
https://api.dyspatch.io/drafts

Response samples

Content type
application/vnd.dyspatch.2023.03+json
Copy
 Expand all Collapse all
{
  • "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.03", set the value to "application/vnd.dyspatch.2023.03+json"

Responses

200

Successfully submitted

400

Invalid request

401

Unauthenticated

403

Unauthorized

404

Resource not found

429

Rate limit exceeded

500

Server error

default

Server error

post/drafts/{draftId}/publishRequest
https://api.dyspatch.io/drafts/{draftId}/publishRequest

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.03", set the value to "application/vnd.dyspatch.2023.03+json"

Responses

200

A draft object with the requested ID.

400

Invalid request

401

Unauthenticated

403

Unauthorized

404

Resource not found

429

Rate limit exceeded

500

Server error

default

Server error

get/drafts/{draftId}
https://api.dyspatch.io/drafts/{draftId}

Response samples

Content type
application/vnd.dyspatch.2023.03+json
Copy
 Expand all Collapse all
{
  • "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": "2024-11-25T21:32:36Z",
  • "updatedAt": "2024-11-25T21:32:36Z",
  • "localizations":
    [
    ],
  • "status": "LOCKED_FOR_TRANSLATION",
  • "templateName": "Template Name",
  • "designApprovedDate": "2024-11-25T21:32:36Z"
}

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.03", set the value to "application/vnd.dyspatch.2023.03+json"

Responses

200

A list of localizations

get/drafts/{draftId}/localizations
https://api.dyspatch.io/drafts/{draftId}/localizations

Response samples

Content type
application/vnd.dyspatch.2023.03+json
Copy
 Expand all Collapse all
[
  • {
    }
]

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.03", set the value to "application/vnd.dyspatch.2023.03+json"

Request Body schema: application/json
name
string

Responses

200

Successful upsert

put/drafts/{draftId}/localizations/{languageId}
https://api.dyspatch.io/drafts/{draftId}/localizations/{languageId}

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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.03", set the value to "application/vnd.dyspatch.2023.03+json"

Responses

200

Successful delete

delete/drafts/{draftId}/localizations/{languageId}
https://api.dyspatch.io/drafts/{draftId}/localizations/{languageId}

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.03", set the value to "application/vnd.dyspatch.2023.03+json"

Request Body schema: application/json
property name*
string

Responses

200

Successful

403

Unauthorized

put/drafts/{draftId}/localizations/{languageId}/translations
https://api.dyspatch.io/drafts/{draftId}/localizations/{languageId}/translations

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "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.03+json to get a JSON object, or text/vnd.dyspatch.2023.03+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.03", set the value to "application/vnd.dyspatch.2023.03+json"

Responses

200

Localization keys

get/drafts/{draftId}/localizationKeys
https://api.dyspatch.io/drafts/{draftId}/localizationKeys

Response samples

Content type
application/vnd.dyspatch.2023.03+json
Copy
 Expand all Collapse all
[
  • {
    }
]

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.03", set the value to "application/vnd.dyspatch.2023.03+json"

Responses

200

A localization object with the requested ID

400

Invalid request

401

Unauthenticated

403

Unauthorized

404

Resource not found

429

Rate limit exceeded

500

Server error

default

Server error

get/localizations/{localizationId}
https://api.dyspatch.io/localizations/{localizationId}

Response samples

Content type
application/vnd.dyspatch.2023.03+json
Copy
 Expand all Collapse all
{
  • "id": "loc_g3L7Cw6Hp5wUaf395LehwK",
  • "languages":
    [
    ],
  • "url": "/localizations/loc_g3L7Cw6Hp5wUaf395LehwK",
  • "template": "tem_g3L7Cw6Hp5wU",
  • "compiled":
    {
    },
  • "createdAt": "2024-11-25T21:32:36Z",
  • "updatedAt": "2024-11-25T21:32:36Z",
  • "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.03", set the value to "application/vnd.dyspatch.2023.03+json"

Responses

200

A localization object from the matching draft ID with the requested ID

400

Invalid request

401

Unauthenticated

403

Unauthorized

404

Resource not found

429

Rate limit exceeded

500

Server error

default

Server error

get/localizations/{localizationId}/drafts/{draftId}
https://api.dyspatch.io/localizations/{localizationId}/drafts/{draftId}

Response samples

Content type
application/vnd.dyspatch.2023.03+json
Copy
 Expand all Collapse all
{
  • "id": "loc_g3L7Cw6Hp5wUaf395LehwK",
  • "languages":
    [
    ],
  • "url": "/localizations/loc_g3L7Cw6Hp5wUaf395LehwK",
  • "template": "tem_g3L7Cw6Hp5wU",
  • "compiled":
    {
    },
  • "createdAt": "2024-11-25T21:32:36Z",
  • "updatedAt": "2024-11-25T21:32:36Z",
  • "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.03", set the value to "application/vnd.dyspatch.2023.03+json"

Responses

200

A list of workspaces

400

Invalid request

401

Unauthenticated

403

Unauthorized

429

Rate limit exceeded

500

Server error

default

Server error

get/workspaces
https://api.dyspatch.io/workspaces

Response samples

Content type
application/vnd.dyspatch.2023.03+json
Copy
 Expand all Collapse all
{
  • "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.03", set the value to "application/vnd.dyspatch.2023.03+json"

Responses

200

Folder

400

Invalid request

401

Unauthenticated

403

Unauthorized

429

Rate limit exceeded

500

Server error

default

Server error

get/workspaces/{folderId}
https://api.dyspatch.io/workspaces/{folderId}

Response samples

Content type
application/vnd.dyspatch.2023.03+json
Copy
 Expand all Collapse all
{
  • "id": "fdr_01g0z4d5aw",
  • "name": "Name of Folder",
  • "description": "Description of Folder",
  • "url": "/workspaces/fdr_g3L7Cw6Hp5wUaf395LehwK",
  • "createdAt": "2024-11-25T21:32:36Z",
  • "updatedAt": "2024-11-25T21:32:36Z",
  • "subfolders":
    [
    ]
}

Blocks

List Blocks

Gets a list of Blocks

Authorizations:
Bearer
header Parameters
Accept
required
string

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

Responses

200

A list of blocks

400

Invalid request

401

Unauthenticated

403

Unauthorized

429

Rate limit exceeded

500

Server error

default

Server error

get/blocks
https://api.dyspatch.io/blocks

Response samples

Content type
application/vnd.dyspatch.2023.03+json
Copy
 Expand all Collapse all
{
  • "cursor":
    {
    },
  • "data":
    [
    ]
}

Get Block by ID

Gets a block with the matching ID.

Authorizations:
Bearer
path Parameters
blockId
required
string

A block ID

header Parameters
Accept
required
string

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

Responses

200

A block

400

Invalid request

401

Unauthenticated

403

Unauthorized

429

Rate limit exceeded

500

Server error

default

Server error

get/blocks/{blockId}
https://api.dyspatch.io/blocks/{blockId}

Response samples

Content type
application/vnd.dyspatch.2023.03+json
Copy
 Expand all Collapse all
{
  • "id": "blk_01gpe172x7p6aa1c9grr48efq8",
  • "name": "Header Block",
  • "description": "string",
  • "createdAt": "2024-11-25T21:32:36Z",
  • "updatedAt": "2024-11-25T21:32:36Z",
  • "url": "/blocks/blk_01gpe172x7p6aa1c9grr48efq8"
}

Get localizations on a block

Returns localization metadata for the block

Authorizations:
Bearer
path Parameters
blockId
required
string

A block ID

header Parameters
Accept
required
string

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

Responses

200

A list of localizations

400

Invalid request

401

Unauthenticated

403

Unauthorized

429

Rate limit exceeded

500

Server error

default

Server error

get/blocks/{blockId}/localizations
https://api.dyspatch.io/blocks/{blockId}/localizations

Response samples

Content type
application/vnd.dyspatch.2023.03+json
Copy
 Expand all Collapse all
[
  • {
    }
]

Get localization keys

Returns the list of values that need to be translated for the block.

Authorizations:
Bearer
path Parameters
blockId
required
string

A block ID

header Parameters
Accept
required
string

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

Responses

200

Localization keys

400

Invalid request

401

Unauthenticated

403

Unauthorized

429

Rate limit exceeded

500

Server error

default

Server error

get/blocks/{blockId}/localizationKeys
https://api.dyspatch.io/blocks/{blockId}/localizationKeys

Response samples

Content type
application/vnd.dyspatch.2023.03+json
Copy
 Expand all Collapse all
[
  • {
    }
]

Create or update a block localization

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

Authorizations:
Bearer
path Parameters
blockId
required
string

A block 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.03", set the value to "application/vnd.dyspatch.2023.03+json"

Request Body schema: application/json
name
string

Responses

200

Successful upsert

put/blocks/{blockId}/localizations/{languageId}
https://api.dyspatch.io/blocks/{blockId}/localizations/{languageId}

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "name": "English (US)"
}

Remove a localization

Deletes the localization with the given language ID if it exists

Authorizations:
Bearer
path Parameters
blockId
required
string

A block 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.03", set the value to "application/vnd.dyspatch.2023.03+json"

Responses

200

Successful delete

delete/blocks/{blockId}/localizations/{languageId}
https://api.dyspatch.io/blocks/{blockId}/localizations/{languageId}

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.

Authorizations:
Bearer
path Parameters
blockId
required
string

A block 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.03", set the value to "application/vnd.dyspatch.2023.03+json"

Request Body schema: application/json
property name*
string

Responses

200

Successful

403

Unauthorized

put/blocks/{blockId}/localizations/{languageId}/translations
https://api.dyspatch.io/blocks/{blockId}/localizations/{languageId}/translations

Request samples

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