Skip to content
Frontmail Docs

List sent messages

GET
/v1/history
curl --request GET \
  --url 'https://api.frontmail.dev/v1/history?limit=25' \
  --header 'Authorization: Bearer <token>'

Newest first, cursor pagination. Private key only.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “ Parameters ”

Query Parameters

Section titled “Query Parameters”
limit
integer
default: 25 >= 1 <= 100
cursor
string
<= 2048 characters
status

One status or a comma-separated list, e.g. sent,delivered.

string

One status or a comma-separated list, e.g. sent,delivered.

template_id
string
service_id
string
from

ISO timestamp (inclusive).

string format: date-time

ISO timestamp (inclusive).

to

ISO timestamp (exclusive).

string format: date-time

ISO timestamp (exclusive).

q

Recipient e-mail (exact match).

string
<= 254 characters

Recipient e-mail (exact match).

Responses

Section titled “ Responses ”

200

Section titled “200”

A page of messages.

Media typeapplication/json
object
items
required
Array<object>
object
message_id
required
string
status
required
string
Allowed values: queued held held_service_error sending sent delivered bounced complained failed discarded
template_id
required
string
service_id
required
string
subject
required
string | null
to
required
Array<string>
created_at
required
string
sent_at
required
string | null
next_cursor
required
string | null
Example
{
  "items": [
    {
      "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."
        }
      ]
    }
  }
}

403

Section titled “403”

Forbidden: origin, CAPTCHA (required, failed, not configured), headless, block list, private key required, suspended, unverified owner e-mail, plan limit, dynamic recipient, attachments.

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."
        }
      ]
    }
  }
}