---
title: "List recent sent emails"
method: GET
path: "/emails"
tags: ["Emails"]
---

# List recent sent emails

`GET /emails`

## Request

- Base URL: `https://api.groundmail.dev`
- URL: `https://api.groundmail.dev/emails`
- Auth: HTTP bearer

## Query parameters

- `limit` integer
- `cursor` string
- `test` boolean
- `tenant` string
- `stream` 'transactional' | 'product' | 'newsletter': The mail stream an email went out on, from its `category`. Each stream sends from its own IPs. `newsletter` is for approved accounts only.

## Response `200`

Email list

- ListEmailsResponse
  - `emails` EmailListItem[], required
    - `id` string, required
    - `from` string, required
    - `to` string[], required
    - `cc` string[]
    - `bcc` string[]
    - `reply_to` string[]
    - `subject` string, required
    - `status` 'queued' | 'scheduled' | 'sent' | 'delivered' | 'delayed' | 'held' | 'opened' | 'clicked' | 'bounced' | 'complained' | 'failed' | 'suppressed' | 'cancelled', required: `held`: stopped before sending. Content scanning held it for review (it is then sent or rejected, and you get `email.delivered` or `email.failed`), or sending is paused on the account and it goes out when sending resumes.
    - `last_event` string, nullable
    - `bounce_reason` string, nullable
    - `bounce_type` 'hard' | 'block', nullable: Why the email bounced. Null when it has not bounced (and for complaints). - `hard`: the address cannot receive mail (unknown user, disabled mailbox, domain with no mail server). The address is added to your suppression list. - `block`: the receiving server refused the message because of the sending IP's or domain's reputation or policy, for example a blocklist listing or a mailbox provider's spam policy. The address is fine and is not suppressed, and block bounces do not count toward your bounce rate. You can send to it again later. Present on `email.bounced` and `email.failed` webhook events and on the email object. Treat unknown future values like `hard`.
    - `held_back` HeldBackRecipient[]: Recipients Groundmail validation held back before sending; empty when none were.
      - `email` string, required: The held-back address (trimmed, lowercased)
      - `reason` 'invalid_address' | 'no_mail_server' | 'previously_bounced' | 'mailbox_not_found', required: `invalid_address`: the address cannot exist. `no_mail_server`: the domain does not exist or takes no email (no MX or A record, or a null MX). `previously_bounced`: the address hard-bounced (mailbox does not exist) for a Groundmail sender in the last 90 days. `mailbox_not_found`: Groundmail validation already knows the mailbox does not exist. The last two can be turned off per account in Settings → Suppressions.
    - `test` boolean: `true` when the email never reached the mail server: it was sent with a test key (`gm_test_…`) or only to simulator addresses. Its status and events are simulated, and it is not counted in stats or billing.
    - `stream` 'transactional' | 'product' | 'newsletter': The mail stream an email went out on, from its `category`. Each stream sends from its own IPs. `newsletter` is for approved accounts only.
    - `tenant` string, nullable: The `external_id` of the tenant the email was sent for. Present only on tenant email (`null` once that tenant is deleted).
    - `tags` union
      - EmailTag[]
        - `name` string, required
        - `value` string, required
      - object
    - `scheduled_at` string, date-time, nullable
    - `cancelled_at` string, date-time, nullable
    - `created_at` string, date-time, required
    - `sent_at` string, date-time, nullable
    - `delivered_at` string, date-time, nullable
    - `bounced_at` string, date-time, nullable
    - `opened_at` string, date-time, nullable: First time a recipient opened the email. Requires open tracking on the sending domain.
    - `clicked_at` string, date-time, nullable: First time a recipient clicked a tracked link. Requires click tracking on the sending domain.
  - `has_more` boolean, required
  - `next_cursor` string, nullable, required

## Other responses

- `401`: Missing or invalid API key

---

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