# Quickstart

> Make your first Virtual Mail Public API requests — fetch your user, your inboxes, and recent mail.

Web page: https://reference.earthclassmail.com/v1/rest-api/quickstart/

Go from an API key to your first successful request in a few minutes: fetch
your user, find your inbox, and list the mail received since a given date.

## 1. Get an API key

In the Virtual Mail web application, go to **Settings → Integrations → Custom
API integration** and generate a key. See
[Authentication](https://reference.earthclassmail.com/_llms_txt/v1/rest-api.md#authentication) for details.

Every request sends the key in the `x-api-key` header. In the examples below,
replace `[YOUR_API_KEY]` with your key. The Node.js examples need Node.js 18 or
later; the Python examples need the `requests` package
(`pip install requests`).

## 2. Get your user

Your user ID is needed by the other endpoints.

### curl

```bash
curl "https://api.earthclassmail.com/v1/user" \
  -H "x-api-key: [YOUR_API_KEY]"
```

### Node.js

```js
const res = await fetch("https://api.earthclassmail.com/v1/user", {
  headers: { "x-api-key": "[YOUR_API_KEY]" },
});
console.log(await res.json());
```

### Python

```python
import requests

res = requests.get(
    "https://api.earthclassmail.com/v1/user",
    headers={"x-api-key": "[YOUR_API_KEY]"},
)
print(res.json())
```

Response:

```json
{
  "id": 5001,
  "email": "jane.doe@example.com",
  "first_name": "Jane",
  "last_name": "Doe",
  "username": "jane.doe@example.com",
  "is_admin": true,
  "admin_account_ids": [100, 200],
  "phone": "15551234567",
  "created_at": "2024-01-10T08:00:00Z",
  "updated_at": "2024-06-01T12:00:00Z"
}
```

## 3. List your inboxes

Use the `id` from the previous response (`5001`).

### curl

```bash
curl "https://api.earthclassmail.com/v1/users/5001/inboxes" \
  -H "x-api-key: [YOUR_API_KEY]"
```

### Node.js

```js
const res = await fetch("https://api.earthclassmail.com/v1/users/5001/inboxes", {
  headers: { "x-api-key": "[YOUR_API_KEY]" },
});
console.log(await res.json());
```

### Python

```python
import requests

res = requests.get(
    "https://api.earthclassmail.com/v1/users/5001/inboxes",
    headers={"x-api-key": "[YOUR_API_KEY]"},
)
print(res.json())
```

Response:

```json
{
  "current_page": 1,
  "data": [
    {
      "id": 97599,
      "account": {
        "id": 54297,
        "name": "Bruce Wayne",
        "account_status": "Active",
        "ecm_numbers": ["44725"]
      },
      "piece_counts": {
        "total_piece_count": 32,
        "scanned_piece_count": 2,
        "unscanned_piece_count": 30,
        "unread_piece_count": 0
      },
      "created_at": "2018-07-17T16:30:34Z",
      "updated_at": "2018-07-17T16:30:34Z"
    }
  ],
  "from": 1,
  "to": 1,
  "per_page": 100,
  "last_page": 1,
  "total": 1
}
```

## 4. List recent mail

Use an inbox `id` from the previous response (`97599`). This request returns
the mail received after `2024-06-01T12:00:00Z`, newest first.

### curl

```bash
curl "https://api.earthclassmail.com/v1/inboxes/97599/pieces?filters=received_after:2024-06-01T12:00:00Z&sort_by=received_at&sort_direction=1" \
  -H "x-api-key: [YOUR_API_KEY]"
```

### Node.js

```js
const res = await fetch("https://api.earthclassmail.com/v1/inboxes/97599/pieces?filters=received_after:2024-06-01T12:00:00Z&sort_by=received_at&sort_direction=1", {
  headers: { "x-api-key": "[YOUR_API_KEY]" },
});
console.log(await res.json());
```

### Python

```python
import requests

res = requests.get(
    "https://api.earthclassmail.com/v1/inboxes/97599/pieces?filters=received_after:2024-06-01T12:00:00Z&sort_by=received_at&sort_direction=1",
    headers={"x-api-key": "[YOUR_API_KEY]"},
)
print(res.json())
```

Response (trimmed to the main fields):

```json
{
  "current_page": 1,
  "data": [
    {
      "id": 14460061,
      "inbox_id": 97599,
      "piece_type": "mail",
      "piece_sub_type": "letter",
      "received_at": "2024-06-02T09:14:03Z",
      "sender": { "name": "Internal Revenue Service" },
      "recipient": { "id": 122028, "inbox_id": 97599, "name": "Bruce Wayne" },
      "attributes": ["unscanned", "inbox", "stored"]
    },
    {
      "id": 14460059,
      "inbox_id": 97599,
      "piece_type": "mail",
      "piece_sub_type": "letter",
      "received_at": "2024-06-01T16:42:51Z",
      "sender": null,
      "recipient": { "id": 122028, "inbox_id": 97599, "name": "Bruce Wayne" },
      "attributes": ["unscanned", "read", "inbox", "stored"]
    }
  ],
  "from": 1,
  "to": 2,
  "per_page": 95,
  "last_page": 1,
  "total": 2
}
```

A `401` response means the API key is missing or wrong.

## Next steps

- Results are paged — see [Paging](https://reference.earthclassmail.com/_llms_txt/v1/rest-api.md#paging) to fetch more than the
  first page.
- [Playbooks](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/playbooks.md) walk through common tasks such as
  downloading scans, shredding, and finding detected checks.
- The [API Spec](https://reference.earthclassmail.com/_llms_txt/v1/rest-api/spec.md) lists every endpoint, parameter, and
  response field.