---
title: "List the emails of an app (from the app)"
method: GET
path: "/app-emails"
tags: ["Email"]
---

# List the emails of an app (from the app)

`GET /app-emails`

## Request

- Base URL: `https://api.hypamoon.com/api/v1`
- URL: `https://api.hypamoon.com/api/v1/app-emails`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://app.hypamoon.com/oauth/authorize`, token URL `https://api.hypamoon.com/oauth/token`, scopes: `data:read`)

For an app's own server code only: await env.HYPAMOON.listEmails({ to, status, since, limit, cursor }) does this call without an Authorization header; Hypamoon adds the app's key, and any other key gets 403. Only the emails this app sent with sendEmail or sendEmailBatch, newest first, never those of another app or of the API. Each with its status, reason, status per recipient and timeline, as GET /emails/{id}.

## Query parameters

- `limit` integer
- `cursor` string
- `to` string
- `status` 'queued' | 'sent' | 'delivered' | 'bounced' | 'complained' | 'failed' | 'simulated'
- `since` string, date-time

## Response `200`

The app's emails.

- object
  - `data` object[], required
    - `id` string, uuid, required: The id of the email. sendEmail and sendEmailBatch in an app return it; getEmail(id) reads it back.
    - `app_id` string, uuid, nullable, required: The app that sent it with env.HYPAMOON.sendEmail; null when it was sent with the API, by an agent or from the portal.
    - `from` string, required
    - `to` string, required: The first address in to. All recipients are in recipients.
    - `recipients` object, required: Everyone this email went to. After 90 days the addresses are masked, like s***@example.org.
      - `to` string[], required
      - `cc` string[], required
      - `bcc` string[], required
    - `recipient_count` integer, required: to, cc and bcc together; each counts toward the limits and the bundle.
    - `attachments` object[], required: Name, type and size of each attachment. The content is never stored.
      - `filename` string, required
      - `content_type` string, required
      - `size` integer, required: In bytes.
    - `reply_to` string, nullable, required
    - `subject` string, required
    - `category` 'transactional' | 'other', required
    - `status` 'queued' | 'sent' | 'delivered' | 'bounced' | 'complained' | 'failed' | 'simulated', required: queued, sent (accepted for delivery), delivered, bounced, complained (marked as spam), failed, or simulated (test mode).
    - `recipient_source` 'confirmed' | 'member' | 'form' | 'document' | 'conversation' | 'app_user' | 'buyer' | 'pass_holder' | 'null', nullable, required: Where the recipient appears in the project.
    - `test` boolean, required
    - `error` string, nullable, required
    - `reason` string, nullable, required: Why the email bounced, was marked as spam, is delayed or was not sent, in plain words. null otherwise.
    - `recipient_status` object[], required: The status per recipient. With several recipients one can bounce while the others are delivered.
      - `email` string, required: The address. Masked after 90 days, like s***@example.org.
      - `field` 'to' | 'cc' | 'bcc', required
      - `status` 'queued' | 'sent' | 'delivered' | 'bounced' | 'complained' | 'failed' | 'simulated', required
      - `reason` string, nullable, required: Why it bounced, was marked as spam, is delayed or was not sent.
      - `updated_at` string, nullable, required: When this recipient's status last changed.
    - `timeline` object[], required: Every step, oldest first: queued, then sent (or simulated, or failed), then what the recipient's mail server reported.
      - `status` 'queued' | 'sent' | 'delivered' | 'delayed' | 'bounced' | 'complained' | 'failed' | 'simulated', required: queued, sent, delivered, delayed (the recipient's server has not accepted it yet; retried automatically), bounced, complained, failed or simulated.
      - `at` string, required: When it happened (ISO 8601).
      - `recipient` string, nullable, required: The recipient this step is about; null for every recipient.
      - `reason` string, nullable, required: A short reason in plain words, for delayed, bounced, complained and failed.
    - `created_at` string, required
    - `sent_at` string, nullable, required
    - `delivered_at` string, nullable, required
    - `bounced_at` string, nullable, required
    - `complained_at` string, nullable, required
    - `sender` 'hypamoon_fallback': Only when the project has no verified sending domain of its own: the email went from Hypamoon's address ("<app or project> via Hypamoon"), in a neutral layout without the project's images or design. Tell the user so.
    - `next_step` string: With sender hypamoon_fallback: how to send from the project's own address with its own design.
  - `next_cursor` string, nullable, required

## Other responses

- `400`: Bad Request: invalid_parameter.
- `401`: Unauthorized: unauthorized, missing_api_key, invalid_api_key, api_key_revoked, project_deleted.
- `403`: Forbidden: project_not_enabled, key_mode_mismatch, missing_scope, verification_required, forbidden.
- `429`: Too Many Requests: rate_limited.
- `500`: Internal Server Error: internal_error.
- `503`: Service Unavailable: service_unavailable.

---

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