Skip to content
Documentation

Create Translation Job

POST
/api/v1/workspaces/{workspace_id}/emails/{id}/translation_jobs
curl --request POST \
  --url https://example.com/%7B%7Bapp_url%7D/api/v1/workspaces/1/emails/1/translation_jobs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "target_locales": [ "fr-FR", "de-DE" ], "provider": "ai", "keys": [ "example" ], "provider_options": { "name": "example", "project_template_uid": "example" } }'

Creates a new translation job for the email. While the job is in flight the email is locked for editing.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
workspace_id
required
integer

Workspace ID

id
required
integer

Email ID

Request Body

Section titled “Request Body”
Media typeapplication/json
object
target_locales
required

The locales to translate the email into.

Array<string>
Example
[
  "fr-FR",
  "de-DE"
]
provider
required

The translation provider to use.

string
Allowed values: ai deepl phrase_tms
keys

Optional subset of translation keys to translate; defaults to all translatable fields. Use to re-translate only stale fields.

Array<string>
provider_options
One of:

Options for a Phrase TMS translation job.

object
name
required

Name for the Phrase project.

string
project_template_uid
required

The uid of the project template to create the project from. Obtained from the connector’s project_templates endpoint.

string

Responses

Section titled “Responses”

200

Section titled “200”

Successful

Media typeapplication/json
object
id
required
integer
email_id
required
integer
provider
required

How the job is fulfilled.

string
Allowed values: ai csv deepl phrase_tms
connector_id
required

The localization connector fulfilling this job, or null for built-in providers.

integer | null
status
required
string
Allowed values: pending in_progress completed failed cancelled
source_locale
required

A BCP 47 language tag identifying the language and region of a piece of content. Must carry both a language and a region subtag, and must be in canonical case (lowercase language, titlecase script, uppercase region) — en-GB, not en-gb or en_GB. The region may be a UN M.49 code, so en-001 (world) is valid.

string
locales
required

Per-target-locale progress.

Array<object>
object
locale
required

A BCP 47 language tag identifying the language and region of a piece of content. Must carry both a language and a region subtag, and must be in canonical case (lowercase language, titlecase script, uppercase region) — en-GB, not en-gb or en_GB. The region may be a UN M.49 code, so en-001 (world) is valid.

string
status
required
string
Allowed values: pending in_progress completed failed cancelled
error_message
string | null
created_at
required
string format: date-time
completed_at
required
string | null format: date-time
Example
{
  "id": 12345,
  "email_id": 12345,
  "provider": "ai",
  "connector_id": 12345,
  "status": "pending",
  "source_locale": "en-GB",
  "locales": [
    {
      "locale": "en-GB",
      "status": "pending"
    }
  ],
  "created_at": "2023-08-23T10:30:00.000Z",
  "completed_at": "2023-08-23T10:30:00.000Z"
}

401

Section titled “401”

Unauthorized

Media typeapplication/json
object
message
required
string
Example
{
  "message": "Record not found"
}

403

Section titled “403”

Forbidden

Media typeapplication/json
object
message
required
string
Example
{
  "message": "Record not found"
}

422

Section titled “422”

Unprocessable Entity

Media typeapplication/json
object
message
required
string
errors
required
object
key
additional properties
Array<string>
Example
{
  "errors": {
    "username": [
      "Username is required.",
      "Username must be unique."
    ],
    "email": [
      "Invalid email format."
    ]
  }
}