Skip to content
Registry StackDocsDevelopment (unreleased)

Read the status of a message the caller submitted, or any message for an operator. A message the caller may not see answers exactly like one that does not exist. The recipient is masked, and no part or template data is returned.

GET
/v1/messages/{message_id}
curl --request GET \
  --url https://example.com/v1/messages/example \
  --header 'Authorization: Bearer <token>'

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
message_id
required
string
>= 1 characters

Responses

Section titled “Responses”

200

Section titled “200”

The operation succeeded.

Media typeapplication/json

A message’s status and metadata. The recipient is masked, and no part or template data is returned.

object
acceptedAt
required
string format: date-time
attempts
required
Array<object>
object
attempt
required
integer
>= 1
finishedAt
string format: date-time
generation
required
integer
>= 1
outcome
required
string
Allowed values: in-progress accepted transient permanent maybe-sent interrupted
providerReference
required

Whether the provider returned a reference. The reference itself is not returned.

boolean
startedAt
required
string format: date-time
channel
required
string
Allowed values: email sms
correlationId
string
dispatch
required

What the dispatch worker did. submitted means the provider accepted the message, never that it was delivered.

string
Allowed values: queued sending submitted failed unknown cancelled expired
expiresAt
required
string format: date-time
id
required
string format: uuid
links
required
object
cancel
required
string
self
required
string
notBefore
string format: date-time
report
required

What the provider’s delivery receipts reported. It only moves forward, none then sent then delivered or undelivered, and a final report is never replaced. unavailable: the message’s provider reports no delivery receipts, so submitted is the last status.

string
Allowed values: none sent delivered undelivered unavailable
reportedAt

When the report last moved. Absent while it is none or unavailable.

string format: date-time
senderProfile
required
string
status
required

Derived from dispatch and report: the dispatch state, except that a submitted message whose report is delivered is delivered, and one whose report is undelivered is failed.

string
Allowed values: queued sending submitted delivered failed expired cancelled unknown
template
object
id
required
string
version
required
string
to
required
One of:
object
email
required
Allowed value: redacted
updatedAt
required
string format: date-time
Example
{
  "attempts": [
    {
      "outcome": "in-progress"
    }
  ],
  "channel": "email",
  "dispatch": "queued",
  "report": "none",
  "status": "queued",
  "to": {
    "email": "redacted"
  }
}

401

Section titled “401”

A problem: authentication.refused.

Media typeapplication/problem+json
object
code
required
string
Allowed values: authentication.refused callback.unreadable callback.unverified content.invalid content.too-large content.too-many-segments idempotency.expired idempotency.key-reused message.dispatch-started message.not-visible message.terminal operation.not-authorized profile.not-authorized quota.exceeded rate-limit.exceeded request.body-too-large request.invalid request.method-not-allowed request.not-found request.unprocessable request.unsupported-media-type service.unavailable template.data-invalid template.locale-unavailable template.not-found template.render-refused
detail
required
string
status
required
integer
title
required
string
traceId
required
string
type
required
string
Allowed values: https://id.registrystack.org/problems/registry-messaging/authentication/refused https://id.registrystack.org/problems/registry-messaging/callback/unreadable https://id.registrystack.org/problems/registry-messaging/callback/unverified https://id.registrystack.org/problems/registry-messaging/content/invalid https://id.registrystack.org/problems/registry-messaging/content/too-large https://id.registrystack.org/problems/registry-messaging/content/too-many-segments https://id.registrystack.org/problems/registry-messaging/idempotency/expired https://id.registrystack.org/problems/registry-messaging/idempotency/key-reused https://id.registrystack.org/problems/registry-messaging/message/dispatch-started https://id.registrystack.org/problems/registry-messaging/message/not-visible https://id.registrystack.org/problems/registry-messaging/message/terminal https://id.registrystack.org/problems/registry-messaging/operation/not-authorized https://id.registrystack.org/problems/registry-messaging/profile/not-authorized https://id.registrystack.org/problems/registry-messaging/quota/exceeded https://id.registrystack.org/problems/registry-messaging/rate-limit/exceeded https://id.registrystack.org/problems/registry-messaging/request/body-too-large https://id.registrystack.org/problems/registry-messaging/request/invalid https://id.registrystack.org/problems/registry-messaging/request/method-not-allowed https://id.registrystack.org/problems/registry-messaging/request/not-found https://id.registrystack.org/problems/registry-messaging/request/unprocessable https://id.registrystack.org/problems/registry-messaging/request/unsupported-media-type https://id.registrystack.org/problems/registry-messaging/service/unavailable https://id.registrystack.org/problems/registry-messaging/template/data-invalid https://id.registrystack.org/problems/registry-messaging/template/locale-unavailable https://id.registrystack.org/problems/registry-messaging/template/not-found https://id.registrystack.org/problems/registry-messaging/template/render-refused
code
required
Allowed values: authentication.refused
Example
{
  "code": "authentication.refused",
  "type": "https://id.registrystack.org/problems/registry-messaging/authentication/refused"
}

Headers

Section titled “Headers”
WWW-Authenticate
required
string
Allowed value: Bearer

The bearer challenge.

403

Section titled “403”

A problem: profile.not-authorized.

Media typeapplication/problem+json
object
code
required
string
Allowed values: authentication.refused callback.unreadable callback.unverified content.invalid content.too-large content.too-many-segments idempotency.expired idempotency.key-reused message.dispatch-started message.not-visible message.terminal operation.not-authorized profile.not-authorized quota.exceeded rate-limit.exceeded request.body-too-large request.invalid request.method-not-allowed request.not-found request.unprocessable request.unsupported-media-type service.unavailable template.data-invalid template.locale-unavailable template.not-found template.render-refused
detail
required
string
status
required
integer
title
required
string
traceId
required
string
type
required
string
Allowed values: https://id.registrystack.org/problems/registry-messaging/authentication/refused https://id.registrystack.org/problems/registry-messaging/callback/unreadable https://id.registrystack.org/problems/registry-messaging/callback/unverified https://id.registrystack.org/problems/registry-messaging/content/invalid https://id.registrystack.org/problems/registry-messaging/content/too-large https://id.registrystack.org/problems/registry-messaging/content/too-many-segments https://id.registrystack.org/problems/registry-messaging/idempotency/expired https://id.registrystack.org/problems/registry-messaging/idempotency/key-reused https://id.registrystack.org/problems/registry-messaging/message/dispatch-started https://id.registrystack.org/problems/registry-messaging/message/not-visible https://id.registrystack.org/problems/registry-messaging/message/terminal https://id.registrystack.org/problems/registry-messaging/operation/not-authorized https://id.registrystack.org/problems/registry-messaging/profile/not-authorized https://id.registrystack.org/problems/registry-messaging/quota/exceeded https://id.registrystack.org/problems/registry-messaging/rate-limit/exceeded https://id.registrystack.org/problems/registry-messaging/request/body-too-large https://id.registrystack.org/problems/registry-messaging/request/invalid https://id.registrystack.org/problems/registry-messaging/request/method-not-allowed https://id.registrystack.org/problems/registry-messaging/request/not-found https://id.registrystack.org/problems/registry-messaging/request/unprocessable https://id.registrystack.org/problems/registry-messaging/request/unsupported-media-type https://id.registrystack.org/problems/registry-messaging/service/unavailable https://id.registrystack.org/problems/registry-messaging/template/data-invalid https://id.registrystack.org/problems/registry-messaging/template/locale-unavailable https://id.registrystack.org/problems/registry-messaging/template/not-found https://id.registrystack.org/problems/registry-messaging/template/render-refused
code
required
Allowed values: profile.not-authorized
Example
{
  "code": "profile.not-authorized",
  "type": "https://id.registrystack.org/problems/registry-messaging/authentication/refused"
}

404

Section titled “404”

A problem: message.not-visible.

Media typeapplication/problem+json
object
code
required
string
Allowed values: authentication.refused callback.unreadable callback.unverified content.invalid content.too-large content.too-many-segments idempotency.expired idempotency.key-reused message.dispatch-started message.not-visible message.terminal operation.not-authorized profile.not-authorized quota.exceeded rate-limit.exceeded request.body-too-large request.invalid request.method-not-allowed request.not-found request.unprocessable request.unsupported-media-type service.unavailable template.data-invalid template.locale-unavailable template.not-found template.render-refused
detail
required
string
status
required
integer
title
required
string
traceId
required
string
type
required
string
Allowed values: https://id.registrystack.org/problems/registry-messaging/authentication/refused https://id.registrystack.org/problems/registry-messaging/callback/unreadable https://id.registrystack.org/problems/registry-messaging/callback/unverified https://id.registrystack.org/problems/registry-messaging/content/invalid https://id.registrystack.org/problems/registry-messaging/content/too-large https://id.registrystack.org/problems/registry-messaging/content/too-many-segments https://id.registrystack.org/problems/registry-messaging/idempotency/expired https://id.registrystack.org/problems/registry-messaging/idempotency/key-reused https://id.registrystack.org/problems/registry-messaging/message/dispatch-started https://id.registrystack.org/problems/registry-messaging/message/not-visible https://id.registrystack.org/problems/registry-messaging/message/terminal https://id.registrystack.org/problems/registry-messaging/operation/not-authorized https://id.registrystack.org/problems/registry-messaging/profile/not-authorized https://id.registrystack.org/problems/registry-messaging/quota/exceeded https://id.registrystack.org/problems/registry-messaging/rate-limit/exceeded https://id.registrystack.org/problems/registry-messaging/request/body-too-large https://id.registrystack.org/problems/registry-messaging/request/invalid https://id.registrystack.org/problems/registry-messaging/request/method-not-allowed https://id.registrystack.org/problems/registry-messaging/request/not-found https://id.registrystack.org/problems/registry-messaging/request/unprocessable https://id.registrystack.org/problems/registry-messaging/request/unsupported-media-type https://id.registrystack.org/problems/registry-messaging/service/unavailable https://id.registrystack.org/problems/registry-messaging/template/data-invalid https://id.registrystack.org/problems/registry-messaging/template/locale-unavailable https://id.registrystack.org/problems/registry-messaging/template/not-found https://id.registrystack.org/problems/registry-messaging/template/render-refused
code
required
Allowed values: message.not-visible
Example
{
  "code": "message.not-visible",
  "type": "https://id.registrystack.org/problems/registry-messaging/authentication/refused"
}

405

Section titled “405”

A problem: request.method-not-allowed.

Media typeapplication/problem+json
object
code
required
string
Allowed values: authentication.refused callback.unreadable callback.unverified content.invalid content.too-large content.too-many-segments idempotency.expired idempotency.key-reused message.dispatch-started message.not-visible message.terminal operation.not-authorized profile.not-authorized quota.exceeded rate-limit.exceeded request.body-too-large request.invalid request.method-not-allowed request.not-found request.unprocessable request.unsupported-media-type service.unavailable template.data-invalid template.locale-unavailable template.not-found template.render-refused
detail
required
string
status
required
integer
title
required
string
traceId
required
string
type
required
string
Allowed values: https://id.registrystack.org/problems/registry-messaging/authentication/refused https://id.registrystack.org/problems/registry-messaging/callback/unreadable https://id.registrystack.org/problems/registry-messaging/callback/unverified https://id.registrystack.org/problems/registry-messaging/content/invalid https://id.registrystack.org/problems/registry-messaging/content/too-large https://id.registrystack.org/problems/registry-messaging/content/too-many-segments https://id.registrystack.org/problems/registry-messaging/idempotency/expired https://id.registrystack.org/problems/registry-messaging/idempotency/key-reused https://id.registrystack.org/problems/registry-messaging/message/dispatch-started https://id.registrystack.org/problems/registry-messaging/message/not-visible https://id.registrystack.org/problems/registry-messaging/message/terminal https://id.registrystack.org/problems/registry-messaging/operation/not-authorized https://id.registrystack.org/problems/registry-messaging/profile/not-authorized https://id.registrystack.org/problems/registry-messaging/quota/exceeded https://id.registrystack.org/problems/registry-messaging/rate-limit/exceeded https://id.registrystack.org/problems/registry-messaging/request/body-too-large https://id.registrystack.org/problems/registry-messaging/request/invalid https://id.registrystack.org/problems/registry-messaging/request/method-not-allowed https://id.registrystack.org/problems/registry-messaging/request/not-found https://id.registrystack.org/problems/registry-messaging/request/unprocessable https://id.registrystack.org/problems/registry-messaging/request/unsupported-media-type https://id.registrystack.org/problems/registry-messaging/service/unavailable https://id.registrystack.org/problems/registry-messaging/template/data-invalid https://id.registrystack.org/problems/registry-messaging/template/locale-unavailable https://id.registrystack.org/problems/registry-messaging/template/not-found https://id.registrystack.org/problems/registry-messaging/template/render-refused
code
required
Allowed values: request.method-not-allowed
Example
{
  "code": "request.method-not-allowed",
  "type": "https://id.registrystack.org/problems/registry-messaging/authentication/refused"
}

503

Section titled “503”

A problem: service.unavailable.

Media typeapplication/problem+json
object
code
required
string
Allowed values: authentication.refused callback.unreadable callback.unverified content.invalid content.too-large content.too-many-segments idempotency.expired idempotency.key-reused message.dispatch-started message.not-visible message.terminal operation.not-authorized profile.not-authorized quota.exceeded rate-limit.exceeded request.body-too-large request.invalid request.method-not-allowed request.not-found request.unprocessable request.unsupported-media-type service.unavailable template.data-invalid template.locale-unavailable template.not-found template.render-refused
detail
required
string
status
required
integer
title
required
string
traceId
required
string
type
required
string
Allowed values: https://id.registrystack.org/problems/registry-messaging/authentication/refused https://id.registrystack.org/problems/registry-messaging/callback/unreadable https://id.registrystack.org/problems/registry-messaging/callback/unverified https://id.registrystack.org/problems/registry-messaging/content/invalid https://id.registrystack.org/problems/registry-messaging/content/too-large https://id.registrystack.org/problems/registry-messaging/content/too-many-segments https://id.registrystack.org/problems/registry-messaging/idempotency/expired https://id.registrystack.org/problems/registry-messaging/idempotency/key-reused https://id.registrystack.org/problems/registry-messaging/message/dispatch-started https://id.registrystack.org/problems/registry-messaging/message/not-visible https://id.registrystack.org/problems/registry-messaging/message/terminal https://id.registrystack.org/problems/registry-messaging/operation/not-authorized https://id.registrystack.org/problems/registry-messaging/profile/not-authorized https://id.registrystack.org/problems/registry-messaging/quota/exceeded https://id.registrystack.org/problems/registry-messaging/rate-limit/exceeded https://id.registrystack.org/problems/registry-messaging/request/body-too-large https://id.registrystack.org/problems/registry-messaging/request/invalid https://id.registrystack.org/problems/registry-messaging/request/method-not-allowed https://id.registrystack.org/problems/registry-messaging/request/not-found https://id.registrystack.org/problems/registry-messaging/request/unprocessable https://id.registrystack.org/problems/registry-messaging/request/unsupported-media-type https://id.registrystack.org/problems/registry-messaging/service/unavailable https://id.registrystack.org/problems/registry-messaging/template/data-invalid https://id.registrystack.org/problems/registry-messaging/template/locale-unavailable https://id.registrystack.org/problems/registry-messaging/template/not-found https://id.registrystack.org/problems/registry-messaging/template/render-refused
code
required
Allowed values: service.unavailable
Example
{
  "code": "service.unavailable",
  "type": "https://id.registrystack.org/problems/registry-messaging/authentication/refused"
}

Headers

Section titled “Headers”
Retry-After
required
integer
>= 1

Whole seconds to wait before trying again.