# See an account's mail usage

`GET https://api.mailmasker.org/api/v1/admin/mail-usage`

How much mail one account keeps, and the limit that applies to it.

- Who can use it: Site admins
- Area: Users and roles
- Answers 200 OK when it works
- Page: https://developer.mailmasker.org/admin-mail-usage

The bytes and messages in the account's mailbox, and its limit: its own if one is set, otherwise the 1 TB default (1099511627776 bytes). The mail server sends fresh figures each time the mailbox changes, so an account whose mailbox hasn't changed since that began shows null for both until it next does.

## Parameters

| Name | In | Required | What it is | Example |
|---|---|---|---|---|
| `user_email` | query | yes | The account's address, exactly as the account has it. | `alice@example.com` |

## Good to know

- An address with no account still answers, with null figures and the default limit.
- An address without an @ answers 400.

## Examples

cURL:

```bash
curl -s 'https://api.mailmasker.org/api/v1/admin/mail-usage?user_email=alice%40example.com' \
  -H "Authorization: Bearer $TOKEN"
```

Perl:

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

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

homelab-cli:

There is no homelab-cli command for this yet.

## Response

200 OK:

```json
{
  "user_email": "alice@example.com",
  "used_bytes": 734003200,
  "messages": 4182,
  "limit_bytes": 5368709120
}
```