Mail

List your recent messages

GET/api/v1/mail/messages

Who can use this: Any signed-in accountAs Markdown

The most recent messages in a folder, the oldest of them first. Each uid is the message's lasting number in that folder; use it to read the message. Listing doesn't mark anything as read.

Parameters

Name	Where	What it is
mailbox	query	The folder to list. INBOX if you leave it out.
limit	query	How many of the newest messages to return. 20 if you leave it out.e.g. 10

Good to know

A folder that doesn't exist answers 502, the same as when your mailbox can't be reached.

curl -s 'https://api.mailmasker.org/api/v1/mail/messages?limit=10' \
  -H "Authorization: Bearer $TOKEN"

use Mojo::Base -strict;
use Mojo::UserAgent;

my $ua  = Mojo::UserAgent->new;
my $res = $ua->get('https://api.mailmasker.org/api/v1/mail/messages',
    { Authorization => "Bearer $ENV{TOKEN}" },
    form => { limit => 10 })->result;
die $res->code, ' ', ($res->json('/error') // $res->message), "\n" unless $res->is_success;
print $res->body, "\n";

homelab-cli mail list --limit 10

Response 200 OK

[
  {
    "uid": "41",
    "from": "Alex <alex@example.com>",
    "subject": "Lunch on Friday?",
    "date": "Tue, 3 Nov 2026 12:05:44 -0600"
  },
  {
    "uid": "42",
    "from": "billing@example.com",
    "subject": "Your November invoice",
    "date": "Tue, 3 Nov 2026 21:42:10 -0600"
  }
]