---
title: "Look up a message-id mapping"
method: GET
path: "/v1/messages/lookup"
tags: ["Messages"]
---

# Look up a message-id mapping

`GET /v1/messages/lookup`

## Request

- Base URL: `https://api.winnr.app`
- URL: `https://api.winnr.app/v1/messages/lookup`
- Auth: HTTP bearer

Map between the `Message-ID` you submitted and the `Message-ID` the
upstream email provider assigned at delivery. Provide exactly ONE of
the two query parameters:

- `provider_message_id` (alias: `ses_message_id`) — reverse lookup.
  You hold the provider-assigned id (e.g. from a reply's `In-Reply-To`
  header) and want the original id you generated. Returns at most one
  mapping.
- `original_message_id` — forward lookup. You hold the id you
  submitted and want the provider-assigned id(s). One-to-many: a send
  to N recipients yields N provider ids (one mapping per recipient).

Ids are accepted with or without angle brackets.

Mappings appear roughly 5 minutes after the send and are retained for
90 days. A mapping only exists for mail relayed through an upstream
email provider — that is the mail whose `Message-ID` gets rewritten;
mail sent directly from Winnr infrastructure keeps your original id
and needs no mapping. An empty `data` array means no mapping (yet):
either the send is less than ~5 minutes old, the mail did not relay
through an upstream provider, or the mapping has aged out.

## Query parameters

- `provider_message_id` string
- `ses_message_id` string
- `original_message_id` string

## Response `200`

Matching mappings (empty array when none found)

- object
  - `data` MessageIdMapping[]
    - `original_message_id` string: The Message-ID you submitted (with angle brackets)
    - `provider_message_id` string: The Message-ID the upstream provider assigned at delivery
    - `provider` string: Upstream provider identifier
    - `recipient` string: Recipient address this mapping applies to
    - `sender` string: Envelope sender address
    - `sending_domain` string: Your sending domain
    - `relayed_at` string, date-time: When the message was relayed upstream
  - `count` integer: Number of mappings returned
  - `meta` Meta
    - `request_id` string
    - `timestamp` string, date-time

## Other responses

- `400`: Zero or both lookup parameters provided
- `401`: Authentication required or token invalid

---

[API](https://skmtc.dev/winnr/apis/winnr-api.md) · [All operations](https://skmtc.dev/winnr/apis/winnr-api/llms.txt) · [OpenAPI document](https://skmtc.dev/winnr/apis/winnr-api/revisions/a4f960beb1eb?raw)