Updated November 17, 2026 · Checked against Mail-Archiver's REST API guide, Open Archiver 0.6.2, Bichon 2.4.2 Community, the TrueNAS Mail Archiver, Open Archiver and Tailscale apps, and Tailscale's HTTPS and Serve documentation. Menu names can change between versions.
SETUP GUIDE
Connect MailBurrow to your archive.
Four steps: prepare your archive server, create a read-only key, give the server an HTTPS address, then connect the app.
MailBurrow reads the mail you already archive with Mail-Archiver, Open Archiver or Bichon. It talks only to your own archive servers, over HTTPS, with API keys or access tokens you create. Want to look around first? Tap Try the demo on the setup screen; it uses fictional mail built into the app and needs no server.
- Mail-Archiver: follow steps 1 to 4.
- Open Archiver: follow Open Archiver steps 1 and 2, then steps 3 and 4.
- Bichon: follow Bichon setup, with HTTPS from step 3.
- Several archives: set up one, then add the other in the app. See several archives.
App version: Open Archiver, the server-type choice and several saved archives need MailBurrow 0.4.0 or later. Bichon needs MailBurrow 0.5.0 or later.
How it works
- Your mail providers (IMAP, Microsoft 365)
- Mail-Archiver, Open Archiver or Bichon syncs and stores your mail, on TrueNAS or in Docker
- An HTTPS front door, such as Tailscale Serve or a reverse proxy, in front of the server's plain-HTTP port
- MailBurrow on your phone reads through that address with your API key
- Your archive server does the archiving. MailBurrow never connects to Gmail, Outlook or any mail provider, and never sees your mailbox passwords.
- MailBurrow only reads. It lists accounts or sources, folders and messages, runs searches and downloads attachments you ask for. It can't change, delete or send mail.
- Nothing is kept on the phone. Messages are fetched when you open them and aren't stored for offline reading. Saved archive names, server types, addresses, API keys and selected accounts or sources are kept in the phone's secure storage; user-saved attachments stay where you save them.
- HTTPS is required. The app checks the server's certificate and refuses plain
http://addresses, so your key is never sent unencrypted.
What you need
| Piece | Required? | What it does |
|---|---|---|
| Mail-Archiver 2607.3 or later, or Open Archiver 0.6.2, or Bichon 2.4.2 Community | Yes, at least one | Archives your mail and provides the API. Mail-Archiver's API is off by default. Other Open Archiver and Bichon versions, and Bichon Pro/Enterprise, haven't been tested. |
| An API key (Bichon: an access token) for that server | Yes | Lets the app read the archive with its user's permissions. |
| An HTTPS address with a trusted certificate | Yes | For example https://archive.example.ts.net. Self-signed certificates don't work. |
| Tailscale on the server and the phone | Recommended | Private access from anywhere, plus a free trusted certificate through Tailscale Serve. |
| TrueNAS | Optional | One easy way to run either server, through its community app. Docker on any machine works too. |
| Your own domain and a reverse proxy | Optional | An alternative to Tailscale for the HTTPS address. |
Step 1: Turn on Mail-Archiver's API
The API is controlled by the Api__Enabled setting. While it's off, every /api/ address returns “not found”, and MailBurrow reports Archive API or message unavailable.
TrueNAS app
- Open Apps, select Mail Archiver and choose Edit.
- Under Additional Environment Variables, add Name
Api__Enabledwith Valuetrue. - Save. The app restarts.
- Check the app version is 2607.3 or later; update the app if it isn't.
Docker Compose
Add this to the Mail-Archiver service's environment: list, then recreate the container:
- Api__Enabled=true
Optional settings, from Mail-Archiver's setup guide:
Api__AllowAttachmentDownloadsistrueby default. Leave it on, or attachment downloads in the app will fail.Api__RateLimitPerMinuteis120by default. That's plenty for one phone. If you see Too many requests, wait a minute.
Step 2: Create an API key
A key inherits the permissions of the user who creates it. A regular user's key sees only the mail accounts assigned to that user; an administrator's key sees every account on the server. For a phone, use a regular user that has only the accounts you want to read on it.
- Sign in to Mail-Archiver's web interface as that user.
- Open the API Keys page and create a key. Give it a clear name such as “MailBurrow phone”, and an expiry date if you like.
- Copy the key straight away. It starts with
ma_and is shown only once.
Keep the key private. Never paste it into chats, issue reports or screenshots. If your phone is lost, revoke the key on the same API Keys page; an administrator can revoke any user's keys.
Open Archiver step 1: Create a read-only role
Open Archiver's API needs no setting to turn on. What matters is which user owns the key, because a key has its user's permissions. An administrator's key can see and change everything on the server, so give the phone its own user with a role that can only read the sources you want on it.
- Sign in to Open Archiver as an administrator.
- Open Admin → Roles and create a role, for example “MailBurrow read-only”.
- Find the ID of each source the phone should read: open Archive → Ingestion, select the source, choose View emails, and copy the value after
ingestionSourceId=in the resulting mail-list address (up to the next&, if present). - Enter this policy, replacing
SOURCE_IDwith that ID. To allow several sources, list each ID inside both pairs of brackets.
The first rule lets the user see the source; the second lets them read and search its mail. It allows reading/searching those sources and saving copies of their attachments, but grants no create, update or delete actions.[ { "action": ["read", "search"], "subject": "ingestion", "conditions": { "id": { "$in": ["SOURCE_ID"] } } }, { "action": ["read", "search"], "subject": "archive", "conditions": { "ingestionSourceId": { "$in": ["SOURCE_ID"] } } } ] - Create a user for the phone and give it this custom role. Do not substitute the built-in End user role (which permits changes/deletion) or Read only role (which can read every source).
Open Archiver step 2: Create an API key
- Sign in to Open Archiver as the phone's user from step 1, not as an administrator.
- Open Settings → API Keys and choose Generate API Key. Give it a clear name such as “MailBurrow phone” and choose an expiry.
- Copy the key straight away. It's shown only once.
Keep the key private, as for Mail-Archiver. If your phone is lost, revoke the key on the same page. When a key expires or is revoked, MailBurrow offers Enter a new key for that archive.
What the app shows from Open Archiver
- Sources appear as accounts. Switch between them from the account row, as with Mail-Archiver accounts.
- Search counts are estimates, shown as “about N matches”. Browsing a source shows exact counts.
- There are no folders or server-wide totals. Open Archiver's API has no folder browsing, and its totals are for administrators only. The reader shows each message's folder path instead.
- Sources with Preserve Original File turned on are listed but their messages don't open. Those sources keep each full original message, attachments included, so opening one would download every attachment without asking. Use Open Archiver's website for those sources, or keep the phone's role to sources without that option.
- Searches can match text inside attachments. Results can include full message text and extracted attachment text, not just the matching words. That text is held in memory, never displayed as attachment content, and discarded with the results; it isn't saved on the phone. Attachments themselves download only when you save one.
- Rate limit: by default, Open Archiver allows about 100 requests a minute per client IP address. Devices or keys behind the same proxy/address can share that budget. If you see Too many requests, wait before retrying; changing keys does not reset an IP-based limit.
Step 3: Give the server an HTTPS address
Mail-Archiver and Open Archiver both serve plain HTTP. On TrueNAS, Mail-Archiver's default web port is 30315; for Open Archiver, use the web port shown in its app settings. Put one of the following in front of each server.
Option A: Tailscale Serve (recommended)
Tailscale Serve gives your server an address like https://truenas.your-tailnet.ts.net with a certificate phones trust, reachable only from devices signed in to your Tailscale network.
- In the Tailscale admin console, open DNS, make sure MagicDNS is on, and under HTTPS Certificates select Enable HTTPS.
- On the server, point Serve at Mail-Archiver's port:
Replacetailscale serve --bg 3031530315with your port if it differs. The output shows your HTTPS address.--bgkeeps it running in the background. - Check it:
tailscale serve statusshould showhttps://<machine>.<tailnet>.ts.netforwarding to your port.
Two servers on one machine: each needs its own HTTPS port. Keep the first on the default port, and give the second one another port, such as 8443:
tailscale serve --bg --https=8443 <second-server-port>
Its address then ends in :8443, for example https://truenas.your-tailnet.ts.net:8443. Enter it in the app with the port.
On TrueNAS with the Tailscale community app:
- Follow Tailscale's TrueNAS guide to install the app with an auth key. Then edit the app: untick Userspace and tick Host Network, so Tailscale can reach the Mail Archiver app's port on the host.
- The app's form doesn't include a Serve setting, so run
tailscale serve --bg 30315in a shell inside the Tailscale app, opened from the app's details on the Apps page. After the next restart, runtailscale serve statusagain to check the setting was kept.
The first connection can take a few seconds while Tailscale issues the certificate.
Option B: Your own domain with a reverse proxy
If you already run a reverse proxy such as Caddy, Nginx Proxy Manager or Traefik with Let's Encrypt certificates, add a host like mail.example.com that forwards to Mail-Archiver's port. Some things to watch:
- The certificate must be publicly trusted. Let's Encrypt is fine; self-signed certificates and private certificate authorities aren't supported.
- No redirects. MailBurrow doesn't follow redirects, so its key is never sent anywhere unexpected. Use the final address, and don't put a login page or single sign-on in front of
/api/. - If Mail-Archiver lives under a path such as
https://example.com/mail, enter that full address in the app; the path is kept. - If the address is reachable from the internet, your archive's web interface is too. Consider keeping it private, for example with Tailscale or a VPN, and keep Mail-Archiver updated.
Addresses that won't work
| Address | Why |
|---|---|
http://truenas:30315 or http://100.x.y.z:30315 | Plain HTTP. The app only connects over HTTPS. |
https://192.168.1.10 with a self-signed certificate | The certificate isn't trusted. |
| An address that redirects to another one | The app doesn't follow redirects. Use the final address. |
Bichon: read-only user and access token
These steps need MailBurrow 0.5.0 or later and were tested with Bichon 2.4.2 Community. Pro and Enterprise compatibility is unverified. MailBurrow is an independent client, not Bichon's official app.
- Sign in to Bichon as an administrator and create a dedicated phone user, for example
mailburrow-phone. - Give it the global Member role and Account viewer on only the mail accounts the phone should read. A token inherits its user's permissions; do not use an administrator token. The reader can search/read/save attachments, but cannot tag, repair or delete mail.
- Create an access token for that reader, give it a clear name and choose an expiry. Protect Bichon's interface: it can show the full token again. Never enter your IMAP password in MailBurrow.
- Use your valid HTTPS server address from step 3. In MailBurrow, select Bichon, enter that address and the Access token, then connect. If the token expires or is deleted, use Enter a new access token for the saved archive.
MailBurrow accepts up to 2,000 folders with nesting depth 32 (root zero); larger or malformed folder lists are refused without blocking mail browsing. Use your archive website for larger structures.
Bichon accounts appear as accounts and mailboxes as folders. Folder lists omit server mailbox counts; opening a folder shows the archived total. Search treats typed text literally, without Bichon query operators. Messages use parsed text/HTML with remote content blocked, never raw originals; attachment files download only on explicit save.
Your Bichon server or proxy may log searches. The reviewed 2.4.2 search event includes the query and user name; Community discards that event while Pro/Enterprise may record or forward it. Other server/proxy logs may still exist. See the privacy notice.
Step 4: Connect the app
- Install MailBurrow. The signed Android preview is on GitHub Releases (64-bit ARM phones); compare the APK's SHA-256 with the one in the release notes. iPhone and iPad builds are from source for now.
- If you use Tailscale, install the Tailscale app on your phone, sign in to the same Tailscale network and turn it on.
- Optional check: open your HTTPS address in the phone's browser. You should see your server's sign-in page with no certificate warning.
- Open MailBurrow and choose the server type, Mail-Archiver, Open Archiver or Bichon. The app never guesses it.
- Enter:
- HTTPS server address: for example
truenas.your-tailnet.ts.net, with:8443or another port if you used one.https://is added if you leave it out. Don't add/api. - API key: the key from step 2.
- HTTPS server address: for example
- Tap Connect to archive.
If the key can see more than one mail account or source, switch between them from the account row or in Settings. Disconnect and forget connection in Settings removes the open archive's address and key from the phone; it doesn't revoke the key on the server.
Several archives
MailBurrow can keep up to 20 archives, for example a Mail-Archiver, an Open Archiver and a Bichon server, and switch between them without entering keys again.
- Add one: tap the archive name above the account on the Mail tab, then Add archive. Choose its type, then enter its address and key.
- Switch: tap the archive name and pick another. The previous archive's mail is cleared before the new one loads, and each archive remembers the account or source you last used in it. If one can't be reached, the app says which, and offers Retry saved connection and your other archives. Cancel stops waiting before secure saving begins; it is disabled during the save commit and once the archive is open.
- Manage: Settings → Archives lets you rename an archive, change its address or key, or forget it on this device. Changing an address or key always asks for the key again; the saved key is never sent to a new address. To use another server type, add it as a new archive.
Only one archive is open at a time. There's no combined inbox or search across archives.
If something goes wrong
| Message in the app | Likely cause | What to do |
|---|---|---|
| Enter a valid HTTPS server address… | The address has http://, a username and password, a query or a fragment | Enter just the host name, or https:// plus host name and optional path |
| Unable to connect. Check your HTTPS address and private network. | Tailscale is off on the phone, the address is wrong, or Serve or the proxy isn't running | Turn on Tailscale, open the address in the phone's browser, check tailscale serve status |
| The server certificate could not be verified. | Self-signed or untrusted certificate | Use Tailscale Serve or a Let's Encrypt certificate |
| Your API key was not accepted. | Key mistyped, expired or revoked, or its user is inactive | Create a new key and enter it again; for a saved archive, use Enter a new key |
| This source keeps full original messages… | The Open Archiver source has Preserve Original File turned on | Read it on Open Archiver's website; MailBurrow doesn't open those messages |
| Archive API or message unavailable. | Mail-Archiver's API isn't enabled or it's older than 2607.3, the wrong server type is chosen, the address points at the wrong service, or the message is outside the key's accounts or sources | Check the server type, Api__Enabled=true and the version, then the address |
| The server returned an unexpected response… | The address points at a different service, the wrong server type is chosen, or the server runs a version MailBurrow doesn't support | Check the server type and address, then the server's version against this guide |
| Too many requests. Wait and retry. | More than the rate limit (120 a minute by default for Mail-Archiver, about 100 for Open Archiver) | Wait a minute |
| The server took too long to respond. | Slow connection or busy server | Retry; check the server is running |
Still stuck? See getting help. When asking, never include your API key, server address or real messages.
Privacy and security in short
- Treat the API key as read access to its user's archived mail. Use a regular user, not an administrator, with only the accounts or sources you need. For Open Archiver, use the read-only role from Open Archiver step 1.
- Your server keeps its own access logs. Open Archiver records searches (including the query) and message opens in its audit log. Bichon deployments may record search text and user names, as described above. MailBurrow has no analytics or crash reporting. See the privacy notice.
- MailBurrow downloads an attachment only when you choose to, and saves it where you pick.
- Report security problems privately through the repository's Security tab.
MailBurrow is independent and is not the official Mail-Archiver or Tailscale app.