> ## Documentation Index > Fetch the complete documentation index at: https://docs.meowmail.in/llms.txt > Use this file to discover all available pages before exploring further. # List emails, optionally waiting for new mail > Newest first by default. Pass `since` with the id of the newest email you have already seen to get only newer ones. **With `since`, results are returned oldest-first** so that advancing your cursor to the last item can never skip mail. Pass `wait` (needs an API key) to hold the connection until mail arrives, up to 30 seconds. This is strongly preferred over a tight polling loop: it costs us less and returns to you faster. Bodies are not included — fetch `GET /api/v1/emails/{id}` for those. ## OpenAPI ````yaml https://api.meowmail.in/api/v1/openapi.json get /api/v1/inboxes/{address}/emails openapi: 3.1.0 info: title: MeowMail API version: 1.0.0 summary: Free disposable email API. Receive-only, no accounts, TTL-expiring inboxes. description: >- Create throwaway inboxes and read the mail they receive. Built for automated testing of signup and verification flows, and for privacy tooling. **Inboxes are public.** There is no authorization on inbox contents: anyone who knows the address can read it. Never use MeowMail for anything you would mind a stranger reading, and never for password resets on accounts that matter. **Mail is ephemeral.** Emails are permanently deleted roughly one hour after arrival. **Receive-only.** There is no send endpoint and never will be in this API version. termsOfService: https://docs.meowmail.in/fair-use contact: name: MeowMail url: https://docs.meowmail.in license: name: Free to use under the fair-use policy url: https://docs.meowmail.in/fair-use servers: - url: https://api.meowmail.in description: Production security: - bearerAuth: [] - apiKeyHeader: [] - {} tags: - name: Meta description: Discovery, spec, and health - name: Keys description: Free self-serve API keys - name: Domains description: Domains that accept mail - name: Inboxes description: Create inboxes and read their mail - name: Emails description: Individual emails and attachments paths: /api/v1/inboxes/{address}/emails: get: tags: - Inboxes summary: List emails, optionally waiting for new mail description: >- Newest first by default. Pass `since` with the id of the newest email you have already seen to get only newer ones. **With `since`, results are returned oldest-first** so that advancing your cursor to the last item can never skip mail. Pass `wait` (needs an API key) to hold the connection until mail arrives, up to 30 seconds. This is strongly preferred over a tight polling loop: it costs us less and returns to you faster. Bodies are not included — fetch `GET /api/v1/emails/{id}` for those. operationId: listEmails parameters: - $ref: '#/components/parameters/Address' - name: limit in: query schema: type: integer minimum: 1 maximum: 100 default: 25 - name: since in: query description: >- Return only emails newer than this id. Flips ordering to oldest-first. schema: type: string - name: before in: query description: Return only emails older than this id. Pages backwards. schema: type: string - name: wait in: query description: >- Seconds to hold the connection if the result would be empty. Requires an API key. Set your HTTP client timeout above this value. schema: type: integer minimum: 0 maximum: 30 default: 0 responses: '200': description: >- Email summaries. An empty array means no mail matched (including after a `wait` timed out). content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/EmailSummary' meta: type: object properties: address: type: string count: type: integer next_since: type: - string - 'null' description: Feed straight back as `since` on your next poll. next_before: type: - string - 'null' description: Feed back as `before` to page into older mail. waited: type: boolean '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/KeyRequired' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' components: parameters: Address: name: address in: path required: true description: Full inbox address, URL-encoded. Case-insensitive. schema: type: string examples: - abc123@meowmail.in schemas: EmailSummary: type: object properties: id: type: string address: type: string sender: type: - string - 'null' description: >- The From header as received. Unverified — no SPF/DKIM checks. Do not trust it. mailed_by: type: - string - 'null' description: Domain of the SMTP envelope sender. subject: type: - string - 'null' has_attachments: type: boolean received_at: type: string format: date-time expires_at: type: string format: date-time Error: type: object properties: error: type: object properties: type: type: string enum: - invalid_request - unauthorized - key_required - not_found - rate_limited - quota_exceeded - too_many_waiters - internal_error description: Stable machine-readable code. Branch on this, not on `message`. message: type: string description: Human-readable. May be reworded at any time. docs: type: string responses: BadRequest: description: Malformed request content: application/json: schema: $ref: '#/components/schemas/Error' KeyRequired: description: >- This feature requires an API key. Create a free one with POST /api/v1/keys. content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: No such resource. Most often the email expired. content: application/json: schema: $ref: '#/components/schemas/Error' RateLimited: description: >- Rate limit or daily quota exceeded, or too many long-polls already in flight for this key. Honour `retry-after`. headers: retry-after: schema: type: integer description: Seconds to wait. ratelimit-limit: schema: type: integer ratelimit-remaining: schema: type: integer ratelimit-reset: schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer description: '`Authorization: Bearer mm_...`. Omit entirely to use the anonymous tier.' apiKeyHeader: type: apiKey in: header name: X-API-Key description: Alternative to the Authorization header. ````