List agent activity on a letter

GET

/api/v3/letters/{letterUuid}/agents/runs

const url = 'https://api.tryletterhead.com/api/v3/letters/example/agents/runs?api=true';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

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

curl --request GET \
  --url 'https://api.tryletterhead.com/api/v3/letters/example/agents/runs?api=true' \
  --header 'Authorization: Bearer <token>'

Provided you have any preflight agents, this endpoint allows you to trigger them. The newsletter must be in a preflight status - that is, scheduling - for the agents to actually run.

v3 endpoints expect a company API key.

Authorizations

bearerAuth

Parameters

Path Parameters

letterUuid

required

string

The letter’s unique identifier — an alphanumeric string around ten characters, e.g. ludctamgd6.

Query Parameters

api

required

boolean

When set to true, this endpoint will accept authorization with your API Key.

Responses

200

List Agent Activity on a Letter

application/json

object

items

Array<object>

object

uniqueId

string

agentUniqueId

string

resourceType

integer

resourceUniqueId

string

status

integer

summary

string

validationCode

integer

dispatchedAt

string

startedAt

string

completedAt

string

judgments

Array<object>

object

uniqueId

string

severity

integer

confidence

integer

category

string

finding

string

suggestion

string

state

integer

createdAt

string

updatedAt

string

createdAt

string

updatedAt

string

message

string

total

integer

Example

{
  "items": [
    {
      "uniqueId": "vq5rnof1op",
      "agentUniqueId": "8vbkbo1yqz",
      "resourceType": 0,
      "resourceUniqueId": "35f725edbi",
      "status": 1,
      "summary": "The newsletter has several important areas needing attention, primarily focused on link validity and clarity in messaging. The subject line is also a concern as it is too short, which can affect deliverability. Addressing these issues will enhance the overall quality and effectiveness of the newsletter.",
      "validationCode": 200,
      "dispatchedAt": "2026-03-26 15:02:52",
      "startedAt": "2026-03-26 15:02:56",
      "completedAt": "2026-03-26 15:03:02",
      "judgments": [
        {
          "uniqueId": "yygmhgew0t",
          "severity": 2,
          "confidence": 85,
          "category": "links",
          "finding": "The 'View in browser' link is not valid (isValid: false).",
          "suggestion": "Ensure the link is correctly set up to direct users to the newsletter content.",
          "state": 0,
          "createdAt": "2026-03-26 15:03:02",
          "updatedAt": "2026-03-26 15:03:02"
        },
        {
          "uniqueId": "r377izgox0",
          "severity": 2,
          "confidence": 80,
          "category": "content",
          "finding": "The subject line is too short and may trigger spam filters, impacting reader trust.",
          "suggestion": "Consider revising the subject line to make it longer and more engaging without using spam-triggering language.",
          "state": 0,
          "createdAt": "2026-03-26 15:03:02",
          "updatedAt": "2026-03-26 15:03:02"
        },
        {
          "uniqueId": "7n1si3bgkq",
          "severity": 3,
          "confidence": 75,
          "category": "clarity",
          "finding": "The statement 'Start writing something great...' in the footer is vague and lacks a clear call to action.",
          "suggestion": "Replace this text with a specific call to action, such as 'Explore our latest promotions!' to direct reader engagement.",
          "state": 0,
          "createdAt": "2026-03-26 15:03:02",
          "updatedAt": "2026-03-26 15:03:02"
        }
      ],
      "createdAt": "2026-03-26 15:02:52",
      "updatedAt": "2026-03-26 15:03:02"
    }
  ],
  "message": "",
  "total": 1
}

Still can’t find what you need? Contact support.