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 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 "https://api.earthclassmail.com/v1/user" \
  -H "x-api-key: [YOUR_API_KEY]"

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

import requests

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

Response:

{
  "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 "https://api.earthclassmail.com/v1/users/5001/inboxes" \
  -H "x-api-key: [YOUR_API_KEY]"

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

import requests

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

Response:

{
  "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 "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]"

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());

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):

{
  "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 to fetch more than the first page.
Playbooks walk through common tasks such as downloading scans, shredding, and finding detected checks.
The API Spec lists every endpoint, parameter, and response field.