# The MailMasker API

> The HTTP API behind MailMasker: sign-in and tokens, mail addresses and blocking, Drive, search, sessions, invites, domains and site administration, at https://api.mailmasker.org.

Each link is one ability, as Markdown: what it does, who may use it, its parameters, an example answer, and examples in cURL, Perl and homelab-cli. Start with Getting started for signing in, tokens and errors. Examples use you@example.com and example.com in place of a real address and domain.

## Getting started

- [Getting started](https://developer.mailmasker.org/getting-started.md): the api's address, signing in, sending and refreshing the token, errors, and installing homelab-cli

## Sign-in and tokens

- [Create an account](https://developer.mailmasker.org/create-account.md): `POST /api/v1/auth/register`. Make a new account with an invite, an address and a password. Who: Anyone, with no sign-in.
- [Sign in](https://developer.mailmasker.org/sign-in.md): `POST /api/v1/auth/login`. Trade your address and password for a token and a refresh token. Who: Anyone, with no sign-in.
- [Check your token](https://developer.mailmasker.org/check-token.md): `GET /api/v1/auth/introspect`. Who a token belongs to, when it runs out, and the account's roles. Who: Any signed-in account.
- [Refresh your token](https://developer.mailmasker.org/refresh-token.md): `POST /api/v1/auth/refresh`. Trade your refresh token for a new token and a new refresh token. Who: Anyone, with no sign-in.
- [Sign out](https://developer.mailmasker.org/sign-out.md): `POST /api/v1/auth/logout`. End the session a refresh token belongs to. Who: Anyone, with no sign-in.
- [Change your password](https://developer.mailmasker.org/change-password.md): `POST /api/v1/auth/password`. Set a new password, given your current one. Who: Any signed-in account.

## Sessions

- [List your sessions](https://developer.mailmasker.org/list-sessions.md): `GET /api/v1/auth/sessions`. Every place you are signed in, the newest first. Who: Any signed-in account.
- [End a session](https://developer.mailmasker.org/end-session.md): `DELETE /api/v1/auth/sessions/:jti`. Sign one of your sessions out at once, wherever it is. Who: Any signed-in account.
- [Sign out your other sessions](https://developer.mailmasker.org/sign-out-other-sessions.md): `DELETE /api/v1/auth/sessions`. End every session but this one, or every one including it. Who: Any signed-in account.

## Your account

- [See your account](https://developer.mailmasker.org/account-summary.md): `GET /api/v1/account/summary`. Your address, when the account was made, your recovery address and your roles. Who: Any signed-in account.
- [Set your recovery address](https://developer.mailmasker.org/set-recovery-email.md): `POST /api/v1/account/recovery-email`. Choose where a password-reset link is sent, or remove it. Who: Any signed-in account.
- [See your activity log](https://developer.mailmasker.org/activity-log.md): `GET /api/v1/audit/log`. What your account has done and when, the newest first. Who: Any signed-in account.

## Your addresses and blocking

- [List your addresses](https://developer.mailmasker.org/my-addresses.md): `GET /api/v1/domains/mail-aliases/mine`. Every address you can send from, and the ones you can only receive at. Who: Any signed-in account.
- [List your blocked addresses](https://developer.mailmasker.org/blocked-list.md): `GET /api/v1/domains/recipient-access/mine`. The addresses you've blocked or allowed, alphabetically. Who: Any signed-in account.
- [Block an address](https://developer.mailmasker.org/block-address.md): `POST /api/v1/domains/recipient-access/mine`. Reject all future mail sent to one of your own addresses. Who: Any signed-in account.
- [Unblock an address](https://developer.mailmasker.org/unblock-address.md): `DELETE /api/v1/domains/recipient-access/mine/:recipient`. Take one address off your block list, so its mail is delivered again. Who: Any signed-in account.
- [See your inbox-link setting](https://developer.mailmasker.org/block-link-setting.md): `GET /api/v1/block-link/account`. Whether mail to you gets a "block this address" link, and how. Who: Any signed-in account.
- [Turn inbox links on or off](https://developer.mailmasker.org/block-link-set.md): `PUT /api/v1/block-link/account`. Choose whether your incoming mail carries a "block this address" link. Who: Any signed-in account.

## Mail

- [List your recent messages](https://developer.mailmasker.org/mail-list.md): `GET /api/v1/mail/messages`. The sender, subject and date of the newest messages in one folder. Who: Any signed-in account.
- [Read a message](https://developer.mailmasker.org/mail-read.md): `GET /api/v1/mail/messages/:uid`. One message's sender, subject, date and plain-text body. Who: Any signed-in account.
- [Send a message](https://developer.mailmasker.org/mail-send.md): `POST /api/v1/mail/send`. Send a plain-text email from your own address, or another one you may send from. Who: Any signed-in account.
- [See your mail storage use](https://developer.mailmasker.org/mail-usage.md): `GET /api/v1/mail/usage`. How much space your mail takes, and your mailbox's limit, in bytes. Who: Any signed-in account.

## Drive

- [List your files](https://developer.mailmasker.org/drive-list-files.md): `GET /api/v1/drive/files`. The files in one folder, or at the top level, newest first. Who: Any signed-in account.
- [Upload a file](https://developer.mailmasker.org/drive-upload-file.md): `POST /api/v1/drive/files`. Send a whole file in one request, as a form upload. Who: Any signed-in account.
- [Download a file](https://developer.mailmasker.org/drive-download-file.md): `GET /api/v1/drive/files/:id`. The file's contents, exactly as uploaded. Who: Any signed-in account.
- [Delete a file](https://developer.mailmasker.org/drive-delete-file.md): `DELETE /api/v1/drive/files/:id`. Delete one file at once and for good, or move it to Trash. Who: Any signed-in account.
- [List your folders](https://developer.mailmasker.org/drive-list-folders.md): `GET /api/v1/drive/folders`. The folders inside one folder, or at the top level, by name. Who: Any signed-in account.
- [Create a folder](https://developer.mailmasker.org/drive-create-folder.md): `POST /api/v1/drive/folders`. Make a new folder, at the top level or inside another. Who: Any signed-in account.
- [Delete a folder](https://developer.mailmasker.org/drive-delete-folder.md): `DELETE /api/v1/drive/folders/:id`. Delete a folder and everything inside it, for good or to Trash. Who: Any signed-in account.
- [See your storage use](https://developer.mailmasker.org/drive-usage.md): `GET /api/v1/drive/usage`. How much space your files take, and your limit, in bytes. Who: Any signed-in account.
- [Start a big upload](https://developer.mailmasker.org/drive-upload-start.md): `POST /api/v1/drive/uploads`. Open an upload session, to send a big file in pieces you can resume. Who: Any signed-in account.
- [Check a big upload](https://developer.mailmasker.org/drive-upload-status.md): `GET /api/v1/drive/uploads/:id`. How much of an upload has arrived, so you know where to carry on. Who: Any signed-in account.
- [Send a piece of a big upload](https://developer.mailmasker.org/drive-upload-piece.md): `PATCH /api/v1/drive/uploads/:id`. Add the next piece of the file to an open upload. Who: Any signed-in account.
- [Cancel a big upload](https://developer.mailmasker.org/drive-upload-cancel.md): `DELETE /api/v1/drive/uploads/:id`. Give up on an unfinished upload and throw away what was sent. Who: Any signed-in account.
- [Combine files into one](https://developer.mailmasker.org/drive-combine.md): `POST /api/v1/drive/append-jobs`. Join several files end to end into a new file, in the order you give. Who: Any signed-in account.
- [See how a combine is going](https://developer.mailmasker.org/drive-combine-status.md): `GET /api/v1/drive/append-jobs/:id`. Whether a combine has finished, and how far along it is. Who: Any signed-in account.
- [Zip files and folders](https://developer.mailmasker.org/drive-zip.md): `POST /api/v1/drive/zip-jobs`. Build one zip of the files and folders you pick, saved into your Archives folder. Who: Any signed-in account.
- [See if a zip is ready](https://developer.mailmasker.org/drive-zip-status.md): `GET /api/v1/drive/zip-jobs/:id`. Whether a zip has been built and saved, and where it is. Who: Any signed-in account.
- [Delete several files and folders at once](https://developer.mailmasker.org/drive-delete-many.md): `POST /api/v1/drive/bulk/delete`. Delete a selection of files and folders in one go, for good. Who: Any signed-in account.
- [List what's in Trash](https://developer.mailmasker.org/drive-trash.md): `GET /api/v1/drive/trash`. Every file and folder you've deleted and can still get back. Who: Any signed-in account.
- [Restore a file from Trash](https://developer.mailmasker.org/drive-restore-file.md): `POST /api/v1/drive/files/:id/restore`. Bring a file back out of Trash, to the folder it was in. Who: Any signed-in account.
- [Restore a folder from Trash](https://developer.mailmasker.org/drive-restore-folder.md): `POST /api/v1/drive/folders/:id/restore`. Bring a folder back out of Trash, with everything inside it. Who: Any signed-in account.
- [Delete a file in Trash forever](https://developer.mailmasker.org/drive-purge-file.md): `POST /api/v1/drive/files/:id/purge`. Permanently delete one file that is in Trash. Who: Any signed-in account.
- [Delete a folder in Trash forever](https://developer.mailmasker.org/drive-purge-folder.md): `POST /api/v1/drive/folders/:id/purge`. Permanently delete one folder that is in Trash, with everything inside it. Who: Any signed-in account.
- [Empty your Trash](https://developer.mailmasker.org/drive-empty-trash.md): `POST /api/v1/drive/trash/empty`. Permanently delete everything in your Trash. Who: Any signed-in account.
- [Keep a file out of search](https://developer.mailmasker.org/drive-file-private.md): `POST /api/v1/drive/files/:id/private`. Stop a file turning up in search results, or let it show again. Who: Any signed-in account.
- [Keep a folder out of search](https://developer.mailmasker.org/drive-folder-private.md): `POST /api/v1/drive/folders/:id/private`. Stop everything in a folder turning up in search results, or let it show again. Who: Any signed-in account.
- [Share a file](https://developer.mailmasker.org/drive-share-file.md): `POST /api/v1/drive/files/:id/share`. Make a link to one of your files, for one person or for anyone. Who: Any signed-in account.
- [Share a folder](https://developer.mailmasker.org/drive-share-folder.md): `POST /api/v1/drive/folders/:id/share`. Make a link to one of your folders, for one person or for anyone. Who: Any signed-in account.
- [List your shares](https://developer.mailmasker.org/drive-shares.md): `GET /api/v1/drive/shares`. What you have shared, and what others have shared with you, newest first. Who: Any signed-in account.
- [Revoke a share](https://developer.mailmasker.org/drive-revoke-share.md): `POST /api/v1/drive/shares/:id/revoke`. Turn off a share's link, for everyone who has it. Who: Any signed-in account.

## Search

- [Search your mail and files](https://developer.mailmasker.org/search.md): `GET /api/v1/search`. Find email and files by words, people, dates or type, in one search. Who: Any signed-in account.

## Invites

- [Invite someone](https://developer.mailmasker.org/invite-send.md): `POST /api/v1/invites`. Email someone a link they can use to make an account. Who: Any signed-in account.
- [List your invites](https://developer.mailmasker.org/invite-list.md): `GET /api/v1/invites`. Every invite you have sent, newest first, and what became of each. Who: Any signed-in account.
- [Withdraw an invite](https://developer.mailmasker.org/invite-revoke.md): `DELETE /api/v1/invites/:id`. Cancel a pending invite, so its link stops working. Who: Any signed-in account.
- [See your invite limits](https://developer.mailmasker.org/invite-quota-mine.md): `GET /api/v1/invites/quota`. How many invites you may have waiting at once, and send in a day. Who: Any signed-in account.
- [See someone's invite limits](https://developer.mailmasker.org/invite-quota-show.md): `GET /api/v1/invites/quota/:sender_email`. The invite limits that apply to one sender. Who: Site admins.
- [Set someone's invite limits](https://developer.mailmasker.org/invite-quota-set.md): `PUT /api/v1/invites/quota/:sender_email`. Give one sender their own invite limits in place of the site's defaults. Who: Site admins.

## Background jobs

- [List your jobs](https://developer.mailmasker.org/job-list.md): `GET /api/v1/jobs`. Your 50 most recent background jobs, newest first. Who: Any signed-in account.
- [Check on a job](https://developer.mailmasker.org/job-show.md): `GET /api/v1/jobs/:id`. One job's state and progress, and its file's name and size once it is done. Who: Any signed-in account.
- [Download a job's file](https://developer.mailmasker.org/job-download.md): `GET /api/v1/jobs/:id/download`. The file a finished job made, such as its zip. Who: Any signed-in account.

## Services

- [List the services](https://developer.mailmasker.org/list-services.md): `GET /api/v1/registry`. Every registered service, with its address, port and what it does. Who: Any signed-in account.
- [Find a service](https://developer.mailmasker.org/find-service.md): `GET /api/v1/registry/:feature`. The address homelab-api sends one service's calls to. Who: Any signed-in account.

## Users and roles

- [List accounts](https://developer.mailmasker.org/admin-list-users.md): `GET /api/v1/admin/users`. Every account with its roles and whether it can sign in, or a quick search by address. Who: Site admins.
- [Create an account without an invite](https://developer.mailmasker.org/admin-create-service-account.md): `POST /api/v1/admin/users/service-account`. Make an account directly, for a system mailbox or an operator or test login. Who: Site admins.
- [Suspend or restore an account](https://developer.mailmasker.org/admin-suspend-user.md): `POST /api/v1/admin/users/:id/active`. Stop an account signing in anywhere, or let it sign in again. Who: Site admins.
- [See an account's mail usage](https://developer.mailmasker.org/admin-mail-usage.md): `GET /api/v1/admin/mail-usage`. How much mail one account keeps, and the limit that applies to it. Who: Site admins.
- [Set an account's mail quota](https://developer.mailmasker.org/admin-set-mail-quota.md): `POST /api/v1/admin/users/:id/mail-quota`. Change how much mail one account may keep, or put it back to the default. Who: Site admins.
- [See an account's drive usage](https://developer.mailmasker.org/admin-drive-usage.md): `GET /api/v1/drive/admin/usage`. How much one account keeps in drive, and the limit that applies to it. Who: Site admins.
- [Set an account's drive quota](https://developer.mailmasker.org/admin-set-drive-quota.md): `PUT /api/v1/drive/admin/quota`. Change how much one account may keep in drive, or put it back to the default. Who: Site admins.
- [List roles](https://developer.mailmasker.org/admin-list-roles.md): `GET /api/v1/admin/roles`. Every role, whether it can be deleted, and the permissions it carries. Who: Site admins.
- [Give an account a role](https://developer.mailmasker.org/admin-grant-role.md): `POST /api/v1/admin/users/:id/roles`. Add a role to an account, and with it everything the role allows. Who: Site admins.
- [Take a role from an account](https://developer.mailmasker.org/admin-revoke-role.md): `DELETE /api/v1/admin/users/:id/roles/:role`. Remove one role from an account. Who: Site admins.
- [Create a role](https://developer.mailmasker.org/admin-create-role.md): `POST /api/v1/admin/roles`. Add a new role, with no permissions yet. Who: Site admins.
- [Delete a role](https://developer.mailmasker.org/admin-delete-role.md): `DELETE /api/v1/admin/roles/:name`. Remove a role, taking it from every account that has it. Who: Site admins.
- [List permissions](https://developer.mailmasker.org/admin-list-permissions.md): `GET /api/v1/admin/permissions`. Every permission a role can be given, alphabetically. Who: Site admins.
- [Give a role a permission](https://developer.mailmasker.org/admin-grant-permission.md): `POST /api/v1/admin/roles/:role/permissions/:permission`. Let every account with a role do one more thing. Who: Site admins.
- [Take a permission from a role](https://developer.mailmasker.org/admin-revoke-permission.md): `DELETE /api/v1/admin/roles/:role/permissions/:permission`. Stop a role carrying one permission. Who: Site admins.

## Domains and DNS

- [List domains](https://developer.mailmasker.org/domains-list.md): `GET /api/v1/domains`. Every domain on the system, alphabetically, and whether it takes mail. Who: Site admins.
- [Add a domain](https://developer.mailmasker.org/domain-add.md): `POST /api/v1/domains`. Start serving a domain, for mail, DNS or both. Who: Site admins.
- [See a domain's settings](https://developer.mailmasker.org/domain-show.md): `GET /api/v1/domains/:domain`. One domain, with the same fields as the list of domains. Who: Site admins.
- [Change a domain's settings](https://developer.mailmasker.org/domain-change.md): `PATCH /api/v1/domains/:domain`. Turn a domain's mail, its DNS management, or the whole domain on or off. Who: Site admins.
- [Disable a domain](https://developer.mailmasker.org/domain-disable.md): `DELETE /api/v1/domains/:domain`. Stop accepting mail for a domain, without deleting anything. Who: Site admins.
- [List a domain's DNS records](https://developer.mailmasker.org/dns-records-list.md): `GET /api/v1/domains/:domain/dns/records`. Every record in a domain's DNS zone. Who: Site admins.
- [Create or replace a DNS record](https://developer.mailmasker.org/dns-record-set.md): `POST /api/v1/domains/:domain/dns/records`. Set every value of one name and type in a domain's DNS zone. Who: Site admins.
- [Delete a DNS record](https://developer.mailmasker.org/dns-record-delete.md): `DELETE /api/v1/domains/:domain/dns/records`. Remove every value of one name and type from a domain's DNS zone. Who: Site admins.
- [List extra addresses](https://developer.mailmasker.org/aliases-list.md): `GET /api/v1/domains/mail-aliases`. Every extra address and whole domain routed to an account, and whether it may send from them. Who: Site admins.
- [Give an account an extra address](https://developer.mailmasker.org/alias-add.md): `POST /api/v1/domains/mail-aliases`. Route an address, or a whole domain, to an account, which may also send from it. Who: Site admins.
- [Turn sending on or off for an extra address](https://developer.mailmasker.org/alias-sending.md): `PATCH /api/v1/domains/mail-aliases/:source_pattern`. Let an account send from an extra address, or stop it, while its mail keeps arriving. Who: Site admins.
- [Remove an extra address](https://developer.mailmasker.org/alias-remove.md): `DELETE /api/v1/domains/mail-aliases/:source_pattern`. Stop routing an address or domain to an account, and stop the account sending from it. Who: Site admins.
- [List every block and allow entry](https://developer.mailmasker.org/all-blocks-list.md): `GET /api/v1/domains/recipient-access`. The blocked and allowed addresses of every account and site admin, alphabetically. Who: Site admins.
- [Block or allow any address](https://developer.mailmasker.org/block-any-address.md): `POST /api/v1/domains/recipient-access`. Reject all mail to an address, or let it through ahead of every other check. Who: Site admins.
- [Remove a block or allow entry](https://developer.mailmasker.org/unblock-any-address.md): `DELETE /api/v1/domains/recipient-access/:recipient`. Take any address off the block-and-allow list, whoever put it there. Who: Site admins.
- [See a domain's inbox-link default](https://developer.mailmasker.org/domain-block-link-show.md): `GET /api/v1/block-link/domains/:domain`. Whether accounts on a domain get a "block this address" link by default, and where it goes. Who: Site admins.
- [Set a domain's inbox-link default](https://developer.mailmasker.org/domain-block-link-set.md): `PUT /api/v1/block-link/domains/:domain`. Choose whether accounts on a domain get a "block this address" link, and where it goes. Who: Site admins.

## Catch-all routing

- [List every domain's catch-all](https://developer.mailmasker.org/catch-alls-list.md): `GET /api/v1/domains/catch-alls`. Every domain on the system, alphabetically, with where its catch-all sends mail. Who: Site admins, and accounts granted the domains.catchall permission.
- [See a domain's catch-all](https://developer.mailmasker.org/catch-all-show.md): `GET /api/v1/domains/:domain/catch-all`. Where one domain's catch-all sends mail, if anywhere. Who: Site admins, and accounts granted the domains.catchall permission.
- [Set a domain's catch-all](https://developer.mailmasker.org/catch-all-set.md): `PUT /api/v1/domains/:domain/catch-all`. Send all mail for a domain to one mailbox. Who: Site admins, and accounts granted the domains.catchall permission.
- [Remove a domain's catch-all](https://developer.mailmasker.org/catch-all-clear.md): `DELETE /api/v1/domains/:domain/catch-all`. Stop sending a domain's leftover mail to one mailbox. Who: Site admins, and accounts granted the domains.catchall permission.
- [Check that a mailbox exists](https://developer.mailmasker.org/mailbox-exists.md): `GET /api/v1/mail/recipient-exists`. Whether an address is an active account's mailbox. Who: Site admins, and accounts granted the domains.catchall permission.

## DKIM signing keys

- [List a domain's signing keys](https://developer.mailmasker.org/dkim-list.md): `GET /api/v1/domains/:domain/dkim/selectors`. Every DKIM key a domain has had, by selector, newest first, with its state. Who: Site admins.
- [Make a new signing key](https://developer.mailmasker.org/dkim-rotate.md): `POST /api/v1/domains/:domain/dkim/rotate`. Create a new DKIM key for a domain and publish it in DNS, ready to switch to. Who: Site admins.
- [Switch to a new signing key](https://developer.mailmasker.org/dkim-activate.md): `POST /api/v1/domains/:domain/dkim/:selector/activate`. Start signing a domain's mail with a pending key, and start retiring the old one. Who: Site admins.
- [Retire a signing key now](https://developer.mailmasker.org/dkim-retire.md): `POST /api/v1/domains/:domain/dkim/:selector/retire`. Take an active or retiring key out of use and out of DNS straight away. Who: Site admins.
- [Cancel a new signing key](https://developer.mailmasker.org/dkim-cancel.md): `DELETE /api/v1/domains/:domain/dkim/:selector`. Throw away a pending key that was never switched to. Who: Site admins.

## DMARC reports

- [Check the report fetching](https://developer.mailmasker.org/dmarc-status.md): `GET /api/v1/dmarc/status`. When reports were last fetched, how that went, and how many are stored. Who: Site admins.
- [Summarize DMARC results by domain](https://developer.mailmasker.org/dmarc-summary.md): `GET /api/v1/dmarc/summary`. For each domain, how many messages passed DMARC and how many failed. Who: Site admins.
- [List who sends mail as our domains](https://developer.mailmasker.org/dmarc-sources.md): `GET /api/v1/dmarc/sources`. Each address the reports saw sending in a domain's name, and how much of its mail passed. Who: Site admins.
- [List DMARC reports](https://developer.mailmasker.org/dmarc-reports.md): `GET /api/v1/dmarc/reports`. The reports received, newest first, with who sent each and the period it covers. Who: Site admins.
- [Read a DMARC report](https://developer.mailmasker.org/dmarc-report.md): `GET /api/v1/dmarc/reports/:id`. One report in full, with a line for each sending address it covers. Who: Site admins.

## Fleet and status

- [See high-availability status](https://developer.mailmasker.org/admin-ha-status.md): `GET /api/v1/admin/ha/status`. The database cluster, its connection poolers, the mailbox servers and the internet edges, node by node. Who: Site admins.
- [See the mailbox servers](https://developer.mailmasker.org/admin-dovecot-status.md): `GET /api/v1/admin/dovecot/status`. Which mailbox server is active, which are standing by, and whether each is up. Who: Site admins.
- [List nodes](https://developer.mailmasker.org/admin-list-nodes.md): `GET /api/v1/admin/agent/hosts`. Every node whose agent has ever checked in, and when it last did. Who: Site admins.
- [List services on every node](https://developer.mailmasker.org/admin-service-status.md): `GET /api/v1/admin/agent/status`. Every service each node declares, and whether its agent found it running. Who: Site admins.
- [List services that aren't running](https://developer.mailmasker.org/admin-service-problems.md): `GET /api/v1/admin/agent/status/mismatches`. Only the services whose running state doesn't match what their node declares. Who: Site admins.
- [Map the fleet](https://developer.mailmasker.org/admin-fleet-topology.md): `GET /api/v1/admin/agent/topology`. Every machine, the services on it, and which service talks to which, as a graph. Who: Site admins.
- [Enroll a new node](https://developer.mailmasker.org/admin-enroll-node.md): `POST /api/v1/admin/agent/enroll`. Get a one-time code that lets a new node's agent sign itself in. Who: Site admins.
- [List the fleet's certificates](https://developer.mailmasker.org/admin-list-certificates.md): `GET /api/v1/admin/certstore`. Each TLS certificate the fleet hands out, soonest to expire first. Who: Site admins.

## Optional

- [The whole reference](https://developer.mailmasker.org/reference.md): every page above, in one file
- [reference.json](https://developer.mailmasker.org/reference.json): the same, as JSON
- [The Claude Code skill](https://developer.mailmasker.org/claude-code.md): install it, and Claude looks calls up here as it works