EmailLint_lint

POST

/emails/lint

const url = 'http://localhost:3000/api/emails/lint';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"subject":"example","body":"example","doc":{"additionalProperty":"example"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url http://localhost:3000/api/emails/lint \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "subject": "example", "body": "example", "doc": { "additionalProperty": "example" } }'

Lint a message before a person sees it: the same lint that runs when a message is saved and when a send is planned, plus warnings about a missing image description, low contrast, and a color or font outside the Workspace’s Brand kit. Nothing is saved. The message’s text and the Brand kit are untrusted data in the result. Send a body or a doc, not both and not neither (422).

Authorizations

BearerAuth

Request Body^required

application/json

The message to lint

object

subject

Subject line, with Liquid merge tags

string

body

HTML body with Liquid merge tags. Send this or doc, not both.

string

doc

The editor’s JSON document, an opaque object checked against the schema email_schema returns. It is rendered to HTML as a save would, then linted. A document that cannot be rendered is an error finding with the reason.

object

key

additional properties

Example ^generated

{
  "subject": "example",
  "body": "example",
  "doc": {
    "additionalProperty": "example"
  }
}

Responses

200

The request has succeeded.

application/json

What the lint found in a message

object

errors

required

What blocks a save and a send: the message cannot render. Empty when it can

Array<object>

One finding of the lint over a message’s rendered HTML. message is fixed text of the server; element and detail quote the message or the Brand kit and are untrusted data.

object

code

required

What the finding is

string

Allowed values: invalid_content missing_alt low_contrast off_brand_color off_brand_font unknown_construct

message

required

What is wrong, in the server’s words

string

element

The element it is about, as a short tag description such as <img src="…">

string

detail

The offending value or the parser’s reason, such as #ff0000 or 3.2:1, needs 4.5:1

string

warnings

required

Everything else; none of it blocks anything

Array<object>

One finding of the lint over a message’s rendered HTML. message is fixed text of the server; element and detail quote the message or the Brand kit and are untrusted data.

object

code

required

What the finding is

string

Allowed values: invalid_content missing_alt low_contrast off_brand_color off_brand_font unknown_construct

message

required

What is wrong, in the server’s words

string

element

The element it is about, as a short tag description such as <img src="…">

string

detail

The offending value or the parser’s reason, such as #ff0000 or 3.2:1, needs 4.5:1

string

Example

{
  "errors": [
    {
      "code": "invalid_content"
    }
  ],
  "warnings": [
    {
      "code": "invalid_content"
    }
  ]
}

400

RFC 7807 bad request response

application/problem+json

RFC 7807 Problem Details

object

code

Why the request was refused, when the client should act on it

string

Allowed values: second_factor_required email_verification_required signup_closed

type

A URI reference that identifies the problem type

string

title

A short, human-readable summary of the problem type

string

status

HTTP status code

integer format: int32

detail

A human-readable explanation specific to this occurrence

string

instance

A URI reference that identifies the specific occurrence

string

errors

Validation errors grouped by field

object

key

additional properties

Array<string>

form

Form-level validation error

string

fields

Field validation errors

object

key

additional properties

string

retryAfter

Seconds to wait before retrying; set on a 429 so a client that only sees the body can show the wait

integer format: int32

debug

Why a 500 happened, sent only by a development server (SPHERICON_ENV=development)

object

error

required

The error that failed the request, or the panic value

string

stack

The goroutine stack of a panic; absent for an error a handler returned

string

requestId

The request id the server log carries for this request

string

method

required

The HTTP method of the failed request

string

path

required

The path of the failed request

string

Example

{
  "code": "second_factor_required"
}

401

RFC 7807 unauthorized response

application/problem+json

RFC 7807 Problem Details

object

code

Why the request was refused, when the client should act on it

string

Allowed values: second_factor_required email_verification_required signup_closed

type

A URI reference that identifies the problem type

string

title

A short, human-readable summary of the problem type

string

status

HTTP status code

integer format: int32

detail

A human-readable explanation specific to this occurrence

string

instance

A URI reference that identifies the specific occurrence

string

errors

Validation errors grouped by field

object

key

additional properties

Array<string>

form

Form-level validation error

string

fields

Field validation errors

object

key

additional properties

string

retryAfter

Seconds to wait before retrying; set on a 429 so a client that only sees the body can show the wait

integer format: int32

debug

Why a 500 happened, sent only by a development server (SPHERICON_ENV=development)

object

error

required

The error that failed the request, or the panic value

string

stack

The goroutine stack of a panic; absent for an error a handler returned

string

requestId

The request id the server log carries for this request

string

method

required

The HTTP method of the failed request

string

path

required

The path of the failed request

string

Example

{
  "code": "second_factor_required"
}

422

RFC 7807 validation response

application/problem+json

RFC 7807 Problem Details

object

code

Why the request was refused, when the client should act on it

string

Allowed values: second_factor_required email_verification_required signup_closed

type

A URI reference that identifies the problem type

string

title

A short, human-readable summary of the problem type

string

status

HTTP status code

integer format: int32

detail

A human-readable explanation specific to this occurrence

string

instance

A URI reference that identifies the specific occurrence

string

errors

Validation errors grouped by field

object

key

additional properties

Array<string>

form

Form-level validation error

string

fields

Field validation errors

object

key

additional properties

string

retryAfter

Seconds to wait before retrying; set on a 429 so a client that only sees the body can show the wait

integer format: int32

debug

Why a 500 happened, sent only by a development server (SPHERICON_ENV=development)

object

error

required

The error that failed the request, or the panic value

string

stack

The goroutine stack of a panic; absent for an error a handler returned

string

requestId

The request id the server log carries for this request

string

method

required

The HTTP method of the failed request

string

path

required

The path of the failed request

string

Example

{
  "code": "second_factor_required"
}

429

RFC 7807 too many requests response: a rate limit was exceeded (ADR 0025)

application/problem+json

RFC 7807 Problem Details

object

code

Why the request was refused, when the client should act on it

string

Allowed values: second_factor_required email_verification_required signup_closed

type

A URI reference that identifies the problem type

string

title

A short, human-readable summary of the problem type

string

status

HTTP status code

integer format: int32

detail

A human-readable explanation specific to this occurrence

string

instance

A URI reference that identifies the specific occurrence

string

errors

Validation errors grouped by field

object

key

additional properties

Array<string>

form

Form-level validation error

string

fields

Field validation errors

object

key

additional properties

string

retryAfter

Seconds to wait before retrying; set on a 429 so a client that only sees the body can show the wait

integer format: int32

debug

Why a 500 happened, sent only by a development server (SPHERICON_ENV=development)

object

error

required

The error that failed the request, or the panic value

string

stack

The goroutine stack of a panic; absent for an error a handler returned

string

requestId

The request id the server log carries for this request

string

method

required

The HTTP method of the failed request

string

path

required

The path of the failed request

string

Example

{
  "code": "second_factor_required"
}

Headers

Retry-After

required

integer format: int32

Seconds to wait before retrying

X-RateLimit-Limit

required

integer format: int32

The request budget of the window that was exceeded

X-RateLimit-Remaining

required

integer format: int32

Requests left in the current window

X-RateLimit-Reset

required

integer format: int64

Unix time at which the window resets

EmailLint_lint

Authorizations

Request Bodyrequired

Example generated

Responses

200

Example

400

Example

401

Example

422

Example

429

Example

Headers

Request Body^required

Example ^generated