Skip to content
Frontmail Docs

Get the status of a message

GET
/v1/messages/{id}
curl --request GET \
  --url https://api.frontmail.dev/v1/messages/msg_01j9z3m2c7v8b9n0m1q2w3e4r5 \
  --header 'Authorization: Bearer <token>'

With a private key (Authorization: Bearer) any message of the organization; otherwise pass the status_token returned by the send call in the X-Frontmail-Status-Token header (preferred – query strings end up in access logs) or, for backward compatibility, as ?token=.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters”
id
required

Message id

string
>= 1 characters <= 64 characters
Example
msg_01j9z3m2c7v8b9n0m1q2w3e4r5

Message id

Query Parameters

Section titled “Query Parameters”
token

Deprecated: status_token from the send response. Use the X-Frontmail-Status-Token header.

string
<= 200 characters

Deprecated: status_token from the send response. Use the X-Frontmail-Status-Token header.

Header Parameters

Section titled “Header Parameters”
x-frontmail-status-token

status_token from the send response (preferred over ?token=).

string
<= 200 characters

status_token from the send response (preferred over ?token=).

Responses

Section titled “ Responses ”

200

Section titled “200”

Message status and timeline.

Media typeapplication/json
object
message_id
required
string
status
required
string
Allowed values: queued held held_service_error sending sent delivered bounced complained failed discarded
created_at
required
string
sent_at
required
string | null
template_id
required
string
service_id
required
string
events
required
Array<object>
object
type
required
string
at
required
string
Example
{
  "status": "queued"
}

400

Section titled “400”

Invalid request body, query or Idempotency-Key (invalid_body, bad_request, invalid_idempotency_key).

Media typeapplication/json
object
error
required
object
code
required

Stable error code. See https://docs.frontmail.dev/reference/errors/.

string
Allowed values: bad_request invalid_body invalid_idempotency_key unauthorized invalid_public_key invalid_private_key insufficient_credits forbidden origin_not_allowed captcha_required captcha_failed captcha_not_configured headless_blocked recipient_blocked private_key_required private_key_in_browser email_not_verified organization_suspended plan_limit_reached dynamic_recipient_not_allowed dynamic_recipient_requires_captcha dynamic_field_not_allowed link_not_allowed attachments_not_allowed not_found service_not_found template_not_found message_not_found conflict idempotency_conflict payload_too_large attachment_too_large invalid_template_params template_render_failed invalid_recipient service_unavailable_for_template sender_not_configured rate_limited test_send_limit recipient_suppressed internal_error provider_error service_unavailable
message
required
string
docs_url
required
string format: uri
details
Example
{
  "error": {
    "code": "invalid_template_params",
    "message": "Invalid template parameters. email: Enter a valid e-mail address.",
    "docs_url": "https://docs.frontmail.dev/reference/errors/#invalid-template-params",
    "details": {
      "issues": [
        {
          "param": "email",
          "code": "invalid_email",
          "message": "Enter a valid e-mail address."
        }
      ]
    }
  }
}

401

Section titled “401”

Missing or invalid key (unauthorized, invalid_public_key, invalid_private_key).

Media typeapplication/json
object
error
required
object
code
required

Stable error code. See https://docs.frontmail.dev/reference/errors/.

string
Allowed values: bad_request invalid_body invalid_idempotency_key unauthorized invalid_public_key invalid_private_key insufficient_credits forbidden origin_not_allowed captcha_required captcha_failed captcha_not_configured headless_blocked recipient_blocked private_key_required private_key_in_browser email_not_verified organization_suspended plan_limit_reached dynamic_recipient_not_allowed dynamic_recipient_requires_captcha dynamic_field_not_allowed link_not_allowed attachments_not_allowed not_found service_not_found template_not_found message_not_found conflict idempotency_conflict payload_too_large attachment_too_large invalid_template_params template_render_failed invalid_recipient service_unavailable_for_template sender_not_configured rate_limited test_send_limit recipient_suppressed internal_error provider_error service_unavailable
message
required
string
docs_url
required
string format: uri
details
Example
{
  "error": {
    "code": "invalid_template_params",
    "message": "Invalid template parameters. email: Enter a valid e-mail address.",
    "docs_url": "https://docs.frontmail.dev/reference/errors/#invalid-template-params",
    "details": {
      "issues": [
        {
          "param": "email",
          "code": "invalid_email",
          "message": "Enter a valid e-mail address."
        }
      ]
    }
  }
}

404

Section titled “404”

Template, service or message not found.

Media typeapplication/json
object
error
required
object
code
required

Stable error code. See https://docs.frontmail.dev/reference/errors/.

string
Allowed values: bad_request invalid_body invalid_idempotency_key unauthorized invalid_public_key invalid_private_key insufficient_credits forbidden origin_not_allowed captcha_required captcha_failed captcha_not_configured headless_blocked recipient_blocked private_key_required private_key_in_browser email_not_verified organization_suspended plan_limit_reached dynamic_recipient_not_allowed dynamic_recipient_requires_captcha dynamic_field_not_allowed link_not_allowed attachments_not_allowed not_found service_not_found template_not_found message_not_found conflict idempotency_conflict payload_too_large attachment_too_large invalid_template_params template_render_failed invalid_recipient service_unavailable_for_template sender_not_configured rate_limited test_send_limit recipient_suppressed internal_error provider_error service_unavailable
message
required
string
docs_url
required
string format: uri
details
Example
{
  "error": {
    "code": "invalid_template_params",
    "message": "Invalid template parameters. email: Enter a valid e-mail address.",
    "docs_url": "https://docs.frontmail.dev/reference/errors/#invalid-template-params",
    "details": {
      "issues": [
        {
          "param": "email",
          "code": "invalid_email",
          "message": "Enter a valid e-mail address."
        }
      ]
    }
  }
}

429

Section titled “429”

Rate limited – see Retry-After (seconds).

Media typeapplication/json
object
error
required
object
code
required

Stable error code. See https://docs.frontmail.dev/reference/errors/.

string
Allowed values: bad_request invalid_body invalid_idempotency_key unauthorized invalid_public_key invalid_private_key insufficient_credits forbidden origin_not_allowed captcha_required captcha_failed captcha_not_configured headless_blocked recipient_blocked private_key_required private_key_in_browser email_not_verified organization_suspended plan_limit_reached dynamic_recipient_not_allowed dynamic_recipient_requires_captcha dynamic_field_not_allowed link_not_allowed attachments_not_allowed not_found service_not_found template_not_found message_not_found conflict idempotency_conflict payload_too_large attachment_too_large invalid_template_params template_render_failed invalid_recipient service_unavailable_for_template sender_not_configured rate_limited test_send_limit recipient_suppressed internal_error provider_error service_unavailable
message
required
string
docs_url
required
string format: uri
details
Example
{
  "error": {
    "code": "invalid_template_params",
    "message": "Invalid template parameters. email: Enter a valid e-mail address.",
    "docs_url": "https://docs.frontmail.dev/reference/errors/#invalid-template-params",
    "details": {
      "issues": [
        {
          "param": "email",
          "code": "invalid_email",
          "message": "Enter a valid e-mail address."
        }
      ]
    }
  }
}

Headers

Section titled “Headers”
Retry-After
required

Seconds to wait before retrying.

string

Seconds to wait before retrying.

500

Section titled “500”

Unexpected error; details.request_id identifies the request.

Media typeapplication/json
object
error
required
object
code
required

Stable error code. See https://docs.frontmail.dev/reference/errors/.

string
Allowed values: bad_request invalid_body invalid_idempotency_key unauthorized invalid_public_key invalid_private_key insufficient_credits forbidden origin_not_allowed captcha_required captcha_failed captcha_not_configured headless_blocked recipient_blocked private_key_required private_key_in_browser email_not_verified organization_suspended plan_limit_reached dynamic_recipient_not_allowed dynamic_recipient_requires_captcha dynamic_field_not_allowed link_not_allowed attachments_not_allowed not_found service_not_found template_not_found message_not_found conflict idempotency_conflict payload_too_large attachment_too_large invalid_template_params template_render_failed invalid_recipient service_unavailable_for_template sender_not_configured rate_limited test_send_limit recipient_suppressed internal_error provider_error service_unavailable
message
required
string
docs_url
required
string format: uri
details
Example
{
  "error": {
    "code": "invalid_template_params",
    "message": "Invalid template parameters. email: Enter a valid e-mail address.",
    "docs_url": "https://docs.frontmail.dev/reference/errors/#invalid-template-params",
    "details": {
      "issues": [
        {
          "param": "email",
          "code": "invalid_email",
          "message": "Enter a valid e-mail address."
        }
      ]
    }
  }
}