MailTube is a private, self-hosted appliance that turns permitted YouTube links into MP4, MP3, or WAV files. Submit links from its web dashboard or by email; both paths use the same durable, resource-bounded queue.
Important
Run MailTube on a home or residential network when possible. YouTube commonly restricts VPS, VPN, and datacenter IP addresses. A PO-token provider can improve compatibility with current attestation checks, but it cannot repair poor IP reputation.
- Polished, responsive Next.js dashboard with live queue progress.
- Flexible email syntax: one link and optional format/quality per line.
- MP4 up to 2160p/best, MP3 from 128k–320k, and 16-bit WAV at 44.1/48 kHz.
- Gmail App Password preset plus generic IMAP/SMTP.
- Local downloads or private R2, S3, and MinIO delivery links.
- SQLite persistence, restart recovery, expiry cleanup, cancellation, and bounded concurrency.
- Textual setup wizard designed for SSH and Raspberry Pi OS Lite.
- One application container with no resident Node.js process.
- Multi-architecture
amd64/arm64release design and hardened Compose defaults.
Prerequisites: a 64-bit Linux, macOS, or Windows machine with Docker and Docker Compose v2. Raspberry Pi OS Lite must be 64-bit.
curl -fsSL https://github.com/cineglobe/MailTube/releases/latest/download/install.sh | shThe installer reopens /dev/tty for the interactive wizard, so the piped command remains interactive. To inspect it before running, download install.sh, review it, then execute it directly. The release installer pulls the signed multi-architecture image from ghcr.io/cineglobe/mailtube. You can also follow the manual Compose guide.
For repeatable unattended deployments, create an owner-only JSON setup file from the example, then run:
chmod 600 setup.json
export MAILTUBE_SETUP_FILE="$PWD/setup.json"
curl -fsSL https://github.com/cineglobe/MailTube/releases/latest/download/install.sh | shFor local development:
cp .env.example .env
docker compose run --rm mailtube mailtube hash-password
# Set the password hash and a random 32+ character session secret in .env
docker compose up --buildOpen http://127.0.0.1:8080.
Put one request on each line. Lines without format or quality use the configured defaults.
https://youtube.com/watch?v=VIDEO_ID mp4 1080p
https://youtu.be/VIDEO_ID mp3 320k
https://youtube.com/watch?v=VIDEO_ID wav 48khz
https://youtube.com/watch?v=VIDEO_ID
| Output | Choices | Default |
|---|---|---|
| MP4 | 360p, 480p, 720p, 1080p, 1440p, 2160p, best | 720p |
| MP3 | 128k, 192k, 256k, 320k | 192k |
| WAV | 44.1 kHz, 48 kHz; 16-bit PCM | 44.1 kHz |
MP4 selects the best available stream at or below the requested height. MP3 bitrate is an encoding target, not an improvement to the source. WAV output can be very large. Playlists are intentionally disabled in v1.
- Use a dedicated Gmail mailbox and dedicated storage credentials.
- Keep the dashboard on localhost, a trusted LAN, or Tailscale Serve.
- MailTube never changes Tailscale Serve routes automatically; the installer prints a port-specific command for you to review.
- Keep sender policy on allowlist-only unless you understand the abuse risk.
- Prefer private object storage links for email delivery. Gmail's 25 MB total attachment limit includes MIME overhead, so MailTube uses an 18 MiB safe ceiling.
- Leave the default 24-hour retention in place unless you have a reason to change it.
Start with installation, Raspberry Pi, Gmail, storage, and configuration.
MailTube has one administrator, strict same-origin sessions, CSRF protection, Argon2id password hashes, private artifacts, non-root containers, a read-only root filesystem, and no telemetry. It does not log credentials or presigned URLs. Public unauthenticated exposure is unsupported.
Read security, privacy and retention, and the security policy before exposing an instance outside your machine.
MailTube is not affiliated with YouTube or Google. You are responsible for copyright, permissions, local law, and platform terms. Do not use MailTube to bypass DRM, paywalls, or access controls. Only download media you are entitled to download.
- Architecture
- Email syntax
- Generic email providers
- R2, AWS S3, and MinIO
- Updates, backup/restore, and yt-dlp troubleshooting
- Development and contributing
Licensed under GNU AGPL-3.0-only.