VoidMail 1.3 — owner guide

VoidMail receives temporary email on infrastructure you control. It includes Paper and CenterStage Luxe, a server operations console, member accounts, a scoped developer API, and a publishing workspace. Temporary mail is not a permanent recovery address. Visitor inboxes cannot send replies.

Hosting and first installation

| Target | Support | | --- | --- | | Clean Ubuntu 24.04 LTS VPS, root/sudo | Recommended installer target | | Clean Ubuntu 22.04 LTS VPS, root/sudo | Accepted by the installer | | cPanel/shared hosting, Windows, non-Ubuntu distributions | Not supported by this installer | | Existing multi-tenant mail/DNS server | Use a separate VPS; provisioning changes server services |

The runtime provisions PHP-FPM, Nginx, MariaDB, Redis, Postfix, PowerDNS, workers, scheduling and TLS. The app requires PHP 8.3 or newer; the installer supplies PHP 8.4. Keep a public IP, a domain you control, the required license and sufficient disk space for updates and backups. Allow inbound HTTP/HTTPS and SMTP (25); DNS (53 TCP/UDP) is needed when using VoidMail-managed authoritative DNS. Your hosting provider must permit the required mail traffic. SMTP credentials for account emails are separate from receiving mail.

From an interactive terminal on a fresh supported VPS:

bash <(curl -fsSL https://install.voidmail.email/install.sh)

Follow guided setup and use its private admin setup link. Protect that link like a password. Normal bootstrap detects an existing installation and exits without reinstalling it. After installation use voidmail status, voidmail doctor and voidmail update.

Use the domain's current authoritative DNS provider or deliberately delegate a dedicated receiving domain. Do not change unrelated nameservers. Point the website to the VPS and configure the MX/A records shown by the domain workspace. The receiving test distinguishes local ingest from a real message arriving over SMTP; one passing stage does not prove all stages.

The installer also provisions a certificate for mail.YOUR_DOMAIN when its public HTTP challenge is reachable, and reloads Postfix after renewal. If DNS is still propagating, voidmail-mail-tls.timer retries every six hours. An existing custom SMTP certificate is retained. Check the actual SMTP certificate separately from the website certificate; website HTTPS alone does not validate mail TLS.

Updating and recovery

For an installation older than 1.3, run voidmail update once over SSH to install the web update bridge. Later use System tools → Core updates, check the available version, confirm your password and acknowledge the backup before starting. The fixed root helper can only check status, inspect the configured official channel, or start the update worker. It cannot accept a custom command or download URL from the browser.

The updater snapshots files, runtime/state and the database under /var/backups/voidmail/app, pauses application work, installs dependencies, applies migrations, upgrades installed official modules, refreshes caches and checks the origin. It preserves the application key, settings, uploaded files, database, custom modules and child themes. Never rotate APP_KEY as part of an update: it protects saved credentials and two-factor secrets.

File/service recovery is attempted on failure. Applied database migrations are not automatically reversed. Inspect the private update log /var/lib/voidmail-update/update.log, retain the backup and restore the matching database snapshot if the old application is incompatible with the new schema. An on-server snapshot is not a substitute for an independent off-server backup. Keep enough free space and test your own restore process. An unavailable update bridge does not mean the application is broken; the CLI remains the recovery path.

Members and outgoing email

Enable Modules → Users. Registration, sign-in, profile/password settings and saved inboxes then become available. Admin Users supports search, confirmed/unconfirmed filters, suspension, restoration and session revocation. Suspending a member invalidates existing sessions; restoring access requires a fresh sign-in. Removing the Users module preserves core member data and inbox ownership so reinstalling can restore access.

Configure Settings → Outgoing email with an SMTP host, port, encryption mode, credentials and sender address. Passwords are encrypted at rest and blank password fields retain the existing value. Send a test only to an address you own or are authorized to contact. Verify sender-domain SPF/DKIM/DMARC with your SMTP provider. Saving SMTP settings proves configuration, not deliverability.

Password-reset links expire after 60 minutes and are consumed once. Reset-request responses do not reveal whether an account exists. Email confirmation can be required by the Users module; registration then fails clearly when outgoing email is unavailable. Members-only receiving domains require a signed-in, confirmed member. Changing a password revokes other sessions.

Google and Facebook sign-in

Create your own OAuth app in the provider console. Copy the exact callback URL from Settings → Social sign-in, enter your client ID/secret and enable the provider. Use HTTPS in production. Google/Facebook configuration must match your production domain; provider review or test-user restrictions may apply. Buttons appear only for configured and enabled providers.

Email matches never silently link accounts. Existing members link a provider from account settings after confirming their password. Provider IDs are stored; OAuth access and refresh tokens are not retained. Google email confirmation is trusted only when the provider explicitly confirms it. Other/unverified claims require local confirmation via outgoing email. A social-only member can set a password immediately after provider sign-in or through recovery. Disconnecting requires a password and revokes sessions.

Admin sign-in protection

Open Profile → Sign-in security, confirm your password, scan the local QR in an authenticator app and enter a current code. Save the ten recovery codes outside the server; each works once. Codes already used cannot be replayed. Temporary admin recovery links still require the second factor. Replacing recovery codes invalidates the previous set. Password changes and session revocation invalidate previously issued recovery links.

Keep another authorized administrator and a private server backup available. Never publish an admin setup/recovery link or recovery codes in a support ticket. Operators have broad administration rights; this release does not provide granular staff roles.

Inbox workspace and message safety

Your active inboxes switches between still-active addresses owned by the current browser or account. Recent metadata alone is not access. Expired/destroyed inboxes cannot be reopened. Account limits count active inboxes; guest limits and alias restrictions still apply.

Both themes provide whole-message .eml export, attachments and verification-code extraction. The export reconstructs an email from stored content/headers/attachments; it is not a byte-for-byte archive of the original SMTP message. Code extraction is contextual and remains a heuristic.

HTML is sanitized and displayed in an isolated frame with remote resources blocked. Sender names, subjects and previews are treated as text. A separate list of message links opens a signed, expiring destination-review page. An optional HTTPS masking-service template can contain {url}; following it shares the destination URL with that service. It is disabled by default. Browser notifications require permission and an active browser lifecycle; this release does not promise push delivery after the browser closes.

Developer API

Issue keys under Developer API. Copy the secret once and keep it on your server. Only a hash is stored. Assign the minimum scopes, an expiry, a per-minute request limit and an active inbox limit. Revoke exposed keys immediately. A key can only access inboxes it created; it does not inherit browser/admin/member inbox access. Member-only domains are not exposed to API keys.

The public /developers reference documents /api/v1 endpoints for domains, inbox creation/list/delete, message list/detail/delete and attachment downloads. Send Authorization: Bearer YOUR_API_KEY over HTTPS. Never put a key in a URL or frontend JavaScript. Lists are paginated; honor Retry-After on 429 responses. Private responses and downloads require the same key and appropriate scope.

Publishing, menus and contact

Journal supports Markdown articles, cover images, authors, topics, draft preview, SEO fields and publication dates. Times are UTC. A published article with a future date becomes public when that time is reached; publication is enforced by the query and does not depend on a scheduler. Preview requires an authenticated admin and sends no-index/no-store headers. Stale concurrent edits are rejected. Unpublishing retains the draft.

Pages supports parent/child navigation, content history, duplication and private previews. Save and restore both reject hierarchy cycles. Navigation provides separate header/footer menus, two-level nesting, order, visibility and translated labels. Only safe internal/HTTP/HTTPS/mailto links are accepted. A populated custom menu replaces the default menu for that location; include the pages you want visible.

The /contact form saves submissions in Contact inbox, even when SMTP notification is unavailable. Configure its destination/settings from that workspace. Mark conversations new, open or resolved and retain private notes. The reply link opens your own email application; saving a status does not send a reply. CAPTCHA/throttling and a honeypot protect the form. Account/contact email delivery and inbox receiving are independent systems.

Languages and accessibility

Languages includes editable English, Spanish and Arabic public phrase catalogs. Spanish/Arabic begin as drafts: review your brand and content, then publish them. Missing translations fall back to English. Add another language, import/export a JSON object and retain placeholders such as :name and :count. The UI shows bundled-catalog coverage; coverage does not translate your own articles, legal pages, ad creative or custom theme code.

Published locales have explicit URLs such as /es/blog, language selectors, hreflang, localized sitemap entries and reading direction. First-visit browser detection is optional; a visitor can explicitly select English. Translate CMS/article content and menu labels separately. The administrative console remains English. Arabic uses RTL layout while email addresses and credentials retain LTR presentation.

CAPTCHA and ads

The bundled CAPTCHA module supports Cloudflare Turnstile, hCaptcha, reCAPTCHA v2, invisible reCAPTCHA and v3. Use provider credentials for the correct hostname and configure each protected action: inbox create/change/destroy, login, registration, recovery and contact. v3 checks action, hostname and score; Turnstile also checks action. Invalid/missing tokens fail closed. Optional fail-open applies to provider outages only and should be chosen deliberately. A local development pass is never accepted in production. Script-load failures offer a retry.

Ads honor global, slot and desktop/mobile switches in both themes. Insert only ad code you trust; administrative custom code intentionally executes on public pages. An optional dismissible adblock message uses a local detection element; blockers can produce false positives/negatives. It does not bypass a visitor's blocker.

Child themes and customizations

Keep Paper or CenterStage Luxe and add a child theme without editing bundled files:

themes/atelier/theme.json
themes/atelier/views/home.blade.php   # optional
public/themes/atelier/theme.css      # optional

Example manifest:

{"name":"Atelier","parent":"paper","description":"Our own editorial treatment"}

Use a lowercase slug of 2–40 letters/digits/hyphens beginning with a letter. The parent is paper or luxe. A missing home override inherits the parent homepage; content/account pages inherit the parent layout. Preview with ?theme=atelier, then select the theme in appearance settings. The optional stylesheet loads after the bundled design and is versioned by file modification time. Preserve the parent's inbox controls/configuration when overriding its Blade template.

Templates are trusted executable server code installed by the owner; there is no arbitrary PHP/ZIP upload form. Updates preserve themes/ and public/themes/. The official Users/CAPTCHA modules update with core while retaining settings, data and enabled state. Third-party modules are left alone. Keep custom module IDs distinct and follow their author's compatibility instructions.

Verification boundaries

Automated tests cover authorization/ownership, account flows, mocked OAuth/CAPTCHA providers, publishing, locales, receiving/cleanup, module upgrades and failure recovery. Browser acceptance is performed against isolated fixture data. Actual OAuth sign-in, SMTP delivery and CAPTCHA challenges require your own valid provider configuration and separate live acceptance. Do not advertise unconfigured integrations as connected. The 1.3 release validation record is in the project handoff; hosting versions accepted by the installer are not a claim that every hosting provider was tested.