# Receiving API

> List and retrieve email received on your domains, and download attachments.

Source: https://mailvina.com/docs/api-reference/receiving · Base URL: https://api.mailvina.com · Guide: https://mailvina.com/docs/receiving

## List received emails

Lists received emails, newest first. Bodies are not included; retrieve one to get them.

`GET /emails/receiving`

**Query parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | `number` | no | 1–100. Default 20. |
| `offset` | `number` | no | Default 0. |

**Request**

```bash
curl -X GET 'https://api.mailvina.com/emails/receiving?limit=20' \
  -H 'Authorization: Bearer mv_xxxxxxxxx'
```

```js
const res = await fetch('https://api.mailvina.com/emails/receiving?limit=20', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.MAILVINA_API_KEY}`,
  },
});
const data = await res.json();
```

```python
import os, requests

res = requests.get(
    "https://api.mailvina.com/emails/receiving?limit=20",
    headers={"Authorization": f"Bearer {os.environ['MAILVINA_API_KEY']}"},
)
print(res.json())
```

**Response**

```json
{
  "object": "list",
  "data": [
    {
      "object": "received_email",
      "id": "b4d17a0e-5f1c-4e8a-9d2b-7c3e6f1a2b90",
      "from": "Ada Lovelace <ada@example.com>",
      "to": [
        "support@inbound.acme.com"
      ],
      "cc": [],
      "reply_to": [],
      "subject": "Order #1042",
      "message_id": "<CAF…@mail.gmail.com>",
      "in_reply_to": null,
      "thread_id": "b4d17a0e-5f1c-4e8a-9d2b-7c3e6f1a2b90",
      "created_at": "2026-11-14T10:00:00.000Z",
      "size": 61840,
      "attachments": [
        {
          "id": "att_1",
          "filename": "receipt.pdf",
          "content_type": "application/pdf",
          "size": 48213
        }
      ]
    }
  ],
  "has_more": false
}
```

## Retrieve received email

Returns one received email with its text and HTML bodies, selected headers and attachment list.

`GET /emails/receiving/:id`

**Path parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes | The received email ID (from the webhook or the list). |

**Request**

```bash
curl -X GET 'https://api.mailvina.com/emails/receiving/:id' \
  -H 'Authorization: Bearer mv_xxxxxxxxx'
```

```js
const res = await fetch('https://api.mailvina.com/emails/receiving/:id', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.MAILVINA_API_KEY}`,
  },
});
const data = await res.json();
```

```python
import os, requests

res = requests.get(
    "https://api.mailvina.com/emails/receiving/:id",
    headers={"Authorization": f"Bearer {os.environ['MAILVINA_API_KEY']}"},
)
print(res.json())
```

**Response**

```json
{
  "object": "received_email",
  "id": "b4d17a0e-5f1c-4e8a-9d2b-7c3e6f1a2b90",
  "from": "Ada Lovelace <ada@example.com>",
  "to": [
    "support@inbound.acme.com"
  ],
  "subject": "Order #1042",
  "thread_id": "b4d17a0e-5f1c-4e8a-9d2b-7c3e6f1a2b90",
  "created_at": "2026-11-14T10:00:00.000Z",
  "size": 61840,
  "attachments": [
    {
      "id": "att_1",
      "filename": "receipt.pdf",
      "content_type": "application/pdf",
      "size": 48213
    }
  ],
  "text": "Hi, my order hasn’t arrived…",
  "html": "<div dir=\"ltr\">Hi, my order hasn’t arrived…</div>",
  "headers": {
    "message-id": "<CAF…@mail.gmail.com>",
    "date": "Sat, 14 Nov 2026 10:00:00 +0000"
  }
}
```

## Get attachment

Returns one attachment with its content base64-encoded.

`GET /emails/receiving/:id/attachments/:attachment_id`

**Path parameters**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` | yes | The received email ID. |
| `attachment_id` | `string` | yes | e.g. `att_1`. |

**Request**

```bash
curl -X GET 'https://api.mailvina.com/emails/receiving/:id/attachments/:attachment_id' \
  -H 'Authorization: Bearer mv_xxxxxxxxx'
```

```js
const res = await fetch('https://api.mailvina.com/emails/receiving/:id/attachments/:attachment_id', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.MAILVINA_API_KEY}`,
  },
});
const data = await res.json();
```

```python
import os, requests

res = requests.get(
    "https://api.mailvina.com/emails/receiving/:id/attachments/:attachment_id",
    headers={"Authorization": f"Bearer {os.environ['MAILVINA_API_KEY']}"},
)
print(res.json())
```

**Response**

```json
{
  "object": "attachment",
  "id": "att_1",
  "filename": "receipt.pdf",
  "content_type": "application/pdf",
  "size": 48213,
  "content": "JVBERi0xLjcK…"
}
```