> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sequenzy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List In-App Messages

> Get a contact's in-app messages and content cards

Returns a contact's in-app messages and content cards, which [in-app sequence steps](../../concepts/in-app-messages) create. Call it from your backend (or a backend that serves your mobile app) and render the items in your app. Requires the `subscribers:read` scope.

With `status=open` (the default) you get what the app should show now:

* messages that were not yet displayed, clicked or dismissed
* cards that were not dismissed
* nothing that has expired

Pinned cards come first, then the newest items. With `status=all` you get the contact's history, newest first.

For browser apps that call Sequenzy directly, use the [public feed](../../concepts/in-app-messages#fetch-from-the-browser) instead.

## Request

Identify the contact with one of `email`, `externalId` or `subscriberId`.

<ParamField query="email" type="string">
  Contact email (case-insensitive).
</ParamField>

<ParamField query="externalId" type="string">
  Contact external ID, for example your user ID.
</ParamField>

<ParamField query="subscriberId" type="string">
  Sequenzy subscriber ID.
</ParamField>

<ParamField query="kind" type="string">
  `message` for modals, banners and full-screen messages, or `card` for content
  cards. Omit for both.
</ParamField>

<ParamField query="status" type="string" default="open">
  `open` for what to show now, or `all` for history.
</ParamField>

<ParamField query="limit" type="number" default="50">
  Maximum items, 1 to 100.
</ParamField>

```bash theme={null}
curl "https://api.sequenzy.com/api/v1/in-app/messages?email=jane@example.com" \
  --header "Authorization: Bearer $SEQUENZY_API_KEY"
```

## Response

<ResponseField name="messages" type="array">
  Items with merge tags already filled in. Render `title` and `body` as plain text.

  <Expandable title="item">
    <ResponseField name="id" type="string">Item ID, used when reporting events.</ResponseField>
    <ResponseField name="kind" type="string">`message` or `card`.</ResponseField>
    <ResponseField name="format" type="string | null">`modal`, `banner` or `fullscreen` for messages; null for cards.</ResponseField>
    <ResponseField name="position" type="string | null">`top` or `bottom` for banners; otherwise null.</ResponseField>
    <ResponseField name="title" type="string">Title text.</ResponseField>
    <ResponseField name="body" type="string">Message text; may contain line breaks.</ResponseField>
    <ResponseField name="imageUrl" type="string | null">https image.</ResponseField>
    <ResponseField name="buttons" type="array">Up to 2 `{ label, action, url }` buttons. `action` is `open_url` (open `url`, an https link or app deep link) or `dismiss`.</ResponseField>
    <ResponseField name="data" type="object">String key/values set on the step for your app's own logic.</ResponseField>
    <ResponseField name="pinned" type="boolean">Cards only; pinned cards sort before other cards. Open messages come before all cards.</ResponseField>
    <ResponseField name="sequenceId" type="string | null">Sequence that created it.</ResponseField>
    <ResponseField name="stepId" type="string | null">Sequence step that created it.</ResponseField>
    <ResponseField name="createdAt" type="string">ISO timestamp.</ResponseField>
    <ResponseField name="expiresAt" type="string | null">When it leaves the open feed. Messages default to 30 days; cards never expire unless the step sets it.</ResponseField>
    <ResponseField name="displayedAt" type="string | null">First displayed report.</ResponseField>
    <ResponseField name="clickedAt" type="string | null">First clicked report.</ResponseField>
    <ResponseField name="clickCount" type="number">Every clicked report.</ResponseField>
    <ResponseField name="dismissedAt" type="string | null">First dismissed report.</ResponseField>
    <ResponseField name="readAt" type="string | null">First read report.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "subscriberId": "sub_456",
    "status": "open",
    "messages": [
      {
        "id": "iam_123",
        "kind": "message",
        "format": "banner",
        "position": "top",
        "title": "Your trial ends in 3 days, Jane",
        "body": "Upgrade to keep your sequences running.",
        "imageUrl": null,
        "buttons": [
          {
            "label": "Upgrade",
            "action": "open_url",
            "url": "https://app.example.com/billing"
          }
        ],
        "data": { "screen": "billing" },
        "pinned": false,
        "sequenceId": "seq_789",
        "stepId": "node_321",
        "createdAt": "2026-10-11T09:00:00.000Z",
        "expiresAt": "2026-11-10T09:00:00.000Z",
        "displayedAt": null,
        "clickedAt": null,
        "clickCount": 0,
        "dismissedAt": null,
        "readAt": null
      }
    ]
  }
  ```

  ```json 400 theme={null}
  {
    "error": "Provide email, externalId or subscriberId to identify the contact."
  }
  ```

  ```json 401 theme={null}
  {
    "error": "Invalid API key"
  }
  ```

  ```json 403 theme={null}
  {
    "error": "API key is missing required scope: subscribers:read"
  }
  ```

  ```json 404 theme={null}
  {
    "error": "Subscriber not found."
  }
  ```
</ResponseExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.