> **Early access.** Send API is available to selected organizations and is not generally available yet. What this page describes may change before it is. To request access, email support@sendops.dev.

# Look up a send request

`GET /v1/messages/{request_id}`

- Host: `https://ingest.sendops.dev`
- Guide (idempotency, limits, retries): [Send API guide](https://developers.sendops.dev/api-reference/send-api)
- Authentication: required (Bearer token)
- Required scope: `api.send`

Resolves a `request_id` returned by `POST /v1/send` — from either a
`200` or a `202` — to what became of it: `sent` with the SES
`message_id`, `in_flight` at the origin, or `failed` with the reason.
It returns status only, never the message's recipients or content.
The request must be looked up with a key of the same environment
(`sk_live_` / `sk_test_`) that sent it.

A request the edge queued (`202`) is `404` until SendOps takes it off
the queue, and the lookup is `503` while the origin is down; see
"Looking up a queued request" in the API description.

A `request_id` is only visible to the organization that made the
request; any other organization gets `404`.

## Path parameters

- `request_id` (string, required) — The `request_id` from the send response. An opaque string.

## Example request

```bash
curl 'https://ingest.sendops.dev/v1/messages/string' \
  -H "Authorization: Bearer $SENDOPS_API_KEY"
```

## Responses

### 200 — The request's current state.

Content type: `application/json`

```json
{
  "request_id": "string",
  "status": "sent",
  "message_id": "string",
  "error": {
    "code": "string",
    "detail": "string"
  }
}
```

### 401 — Missing, malformed, unknown or revoked API key, or a non-API-key credential such as an OAuth token (`code: invalid_key`); or a rotated key past its 24-hour grace window (`code: key_expired`). Carries a `WWW-Authenticate: Bearer` challenge. The edge answers the same codes itself, with `X-SendOps-Path: fallback`, when it checks the key before queueing a send. A revoked key is `invalid_key`; `key_revoked` is never an HTTP response, only a lookup's `error.code`.

Content type: `application/problem+json`

```json
{
  "type": "https://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "code": "invalid_key",
  "request_id": "string",
  "retry_after": 0,
  "limit": 0,
  "used": 0,
  "resets_at": "2026-05-17T20:00:00Z",
  "scope": "string",
  "resource": "string",
  "errors": [
    {
      "field": "string",
      "reason": "string"
    }
  ]
}
```

### 403 — The key lacks the `api.send` scope (`code: invalid_scope`), or the request did not come through the edge at `ingest.sendops.dev` (`code: edge_required`).

Content type: `application/problem+json`

```json
{
  "type": "https://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "code": "invalid_key",
  "request_id": "string",
  "retry_after": 0,
  "limit": 0,
  "used": 0,
  "resets_at": "2026-05-17T20:00:00Z",
  "scope": "string",
  "resource": "string",
  "errors": [
    {
      "field": "string",
      "reason": "string"
    }
  ]
}
```

### 404 — No send request with that id exists in this organization.

Content type: `application/problem+json`

```json
{
  "type": "https://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "code": "invalid_key",
  "request_id": "string",
  "retry_after": 0,
  "limit": 0,
  "used": 0,
  "resets_at": "2026-05-17T20:00:00Z",
  "scope": "string",
  "resource": "string",
  "errors": [
    {
      "field": "string",
      "reason": "string"
    }
  ]
}
```

### 429 — Rate limit exceeded (`code: rate_limited`). Retry after `Retry-After`.

Content type: `application/problem+json`

```json
{
  "type": "https://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "code": "invalid_key",
  "request_id": "string",
  "retry_after": 0,
  "limit": 0,
  "used": 0,
  "resets_at": "2026-05-17T20:00:00Z",
  "scope": "string",
  "resource": "string",
  "errors": [
    {
      "field": "string",
      "reason": "string"
    }
  ]
}
```

### 500 — Unexpected server error (`code: internal_error`). Quote `request_id` to support.

Content type: `application/problem+json`

```json
{
  "type": "https://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "code": "invalid_key",
  "request_id": "string",
  "retry_after": 0,
  "limit": 0,
  "used": 0,
  "resets_at": "2026-05-17T20:00:00Z",
  "scope": "string",
  "resource": "string",
  "errors": [
    {
      "field": "string",
      "reason": "string"
    }
  ]
}
```

### 503 — Temporarily unable to accept the request. `code: overloaded` with
`X-SendOps-Shed: 1` when SendOps is shedding load;
`code: upstream_unavailable` when the organization's AWS SES throttled,
is out of daily quota, could not be reached, or failed without
confirming the send (never with `X-SendOps-Shed`). The edge also
answers `upstream_unavailable` with `Retry-After: 2` and
`X-SendOps-Path: fallback` when it cannot reach the SendOps origin,
the origin times out, or recent failures have it skipping the origin
for a few seconds; and with `X-SendOps-Path: direct` plus
`X-SendOps-Reason: unreplayable` when the origin failed after a body
over 10 MB was already streamed to it. Both codes are retryable after
`Retry-After`, with the same `Idempotency-Key`. A definite SES
refusal of the message (`MessageRejected`, sending paused, unverified
MAIL FROM) is a `400 validation_failed` with SES's reason instead.

Content type: `application/problem+json`

```json
{
  "type": "https://example.com",
  "title": "string",
  "status": 0,
  "detail": "string",
  "code": "invalid_key",
  "request_id": "string",
  "retry_after": 0,
  "limit": 0,
  "used": 0,
  "resets_at": "2026-05-17T20:00:00Z",
  "scope": "string",
  "resource": "string",
  "errors": [
    {
      "field": "string",
      "reason": "string"
    }
  ]
}
```