Dyspatch API (2024.07)

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.2024.07+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 published templates. Up to 25 results returned before results are paginated.

Authorizations:
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 "2024.07", set the value to "application/vnd.dyspatch.2024.07+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.2024.07+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:
path Parameters
templateId
required
string

A template ID

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

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 "2024.07", set the value to "application/vnd.dyspatch.2024.07+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.2024.07+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-07-16T22:53:48Z",
  • "updatedAt": "2024-07-16T22:53:48Z",
  • "publishedDraftId": "tdft_g3L7Cw6Hp5wU",
  • "localizations":
    [
    ]
}

Render Template by ID

Renders a template into HTML using the provided data.

Authorizations:
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 "2024.07", set the value to "application/vnd.dyspatch.2024.07+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.2024.07+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"
}

Render Localized Template by ID

Renders a template into HTML for the selected language using the provided data.

Authorizations:
path Parameters
templateId
required
string

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

Responses

200

Rendered template contents in the selected language, 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}/{languageId}
https://api.dyspatch.io/render/template/{templateId}/{languageId}

Response samples

Content type
application/vnd.dyspatch.2024.07+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 Email drafts for your organization.

Authorizations:
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 "2024.07", set the value to "application/vnd.dyspatch.2024.07+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.2024.07+json
Copy
Expand all Collapse all
{
  • "cursor":
    {
    },
  • "data":
    [
    ]
}

Submit Draft for Approval

Moves the Email draft into submitted state.

Authorizations:
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 "2024.07", set the value to "application/vnd.dyspatch.2024.07+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 Email draft object with the matching ID. The "compiled" field will contain the template in the default, unlocalized form.

Authorizations:
path Parameters
draftId
required
string

A draft ID

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

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 "2024.07", set the value to "application/vnd.dyspatch.2024.07+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.2024.07+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":
    {