Get a transactional send's status

GET

/api/v3/transactionals/{uniqueId}

const url = 'https://api.tryletterhead.com/api/v3/transactionals/example?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/transactionals/example?api=true' \
  --header 'Authorization: Bearer <token>'

Where one transactional send stands, looked up by the uniqueId that POST /api/v3/transactionals/actions/send returned: whether it is still queued, was accepted or refused by SparkPost, and — once accepted — whether it was delivered, bounced, or marked as spam. Refused and bounced sends carry the reason.

Authorization: Bearer token (company-level API key). The caller must be a company administrator, and a company administrator sees only their own company’s sends.

Availability: Requires your tenant to be opted into transactional email, and send status to be enabled for your account. Where either is off, this answers 404.

Statuses:

queued — Letterhead has the send and has not yet had a final answer from SparkPost.
accepted — SparkPost accepted the email. Look it up again later to see what happened next.
refused — SparkPost would not take the email (for example, an address that cannot receive mail), or Letterhead could not reach SparkPost after every retry. reason says which.
delivered — the recipient’s mail server accepted the email.
bounced — the email bounced. reason.code is the bounce type.
spam_complaint — the recipient marked the email as spam.

The latest event wins, so an email that was delivered and later bounced reads bounced.

Authorizations

bearerAuth

Parameters

Path Parameters

uniqueId

required

string

The send’s id, from the actions/send response.

Query Parameters

api

required

boolean

Required. Set to true to authenticate with an API key.

Responses

200

200 OK

application/json

object

items

object

uniqueId

The send’s id, as returned by actions/send.

string

status

string

Allowed values: queued accepted refused delivered bounced spam_complaint

reason

Present for refused and usually for bounced; null otherwise.

object

code

For refused, SparkPost’s error code; no_valid_recipient when SparkPost rejected every recipient, transmission_error when it never answered, or unknown when its error carried no code. For bounced, the bounce type (Hard, Soft, Admin, Block).

string

message

Why the email was refused or bounced, in plain text.

string

nullable

updatedAt

When the status last changed — for delivered, bounced and spam_complaint, the time of that event.

string

message

string

total

integer

Example

{
  "items": {
    "uniqueId": "6cuswtvr7p",
    "status": "refused",
    "reason": {
      "code": "5002",
      "message": "invalid recipient"
    },
    "updatedAt": "2026-10-02 14:02:11"
  },
  "message": "Transactional email status.",
  "total": 1
}

404

No send with this id in your company, the send was made before send status was enabled, or send status or transactional email is not enabled for your account.

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