Email Blog Platform

A modern blog platform inspired by Posterous that allows publishing posts via email.

Your email blog platform is fully functional! Send an email to start publishing.

• 📧 Email-to-Publish: Send an email to publish posts instantly
• 🔒 Email Security: Allowlist and verification system to prevent unauthorized posts
• ✏️ Post Editing: Secure web interface for editing and deleting posts with admin authentication
• 🎨 Multi-format Support: HTML and plain text posts
• 🖼️ Advanced Image Handling:
  • Email attachments automatically processed and added to posts
  • Inline images (cid: references) properly rendered
  • Unreferenced attachments displayed in dedicated section
  • Support for JPEG, PNG, GIF, WebP, and SVG formats
• 📡 RSS Feed: Full RSS 2.0 support for syndication
• 🌐 WebSub: Real-time feed updates via WebSub protocol (configured)
• 🐘 ActivityPub: Full federated social networking with followers, likes, and shares ✅
  • Content negotiation for HTML/JSON responses
  • Actor profile accessible from browsers and ActivityPub clients
• 🦋 AT Protocol: Bluesky integration for cross-platform syndication (configured)
• 🔗 SEO Friendly: Clean URLs with slugified titles
• 📱 Responsive Design: Mobile-first responsive interface with TailwindCSS
• ⚡ Fast: Built on Val Town with SQLite storage and static HTML generation
• 🚀 No JavaScript: Pure HTML/CSS frontend for maximum performance

• index.ts - Main Hono server with HTML generation and API routes ✅
• database/ - SQLite schema and query functions ✅
• services/ - External service integrations ✅

• Email trigger handler with security verification ✅
• Allowlist checking and draft post creation ✅
• Automated verification email sending ✅

• Server-side HTML rendering with TailwindCSS ✅
• No client-side JavaScript dependencies ✅
• Fast loading and SEO optimized ✅

1. Configure Security: Set ALLOWED_EMAIL_ADDRESSES environment variable (see Security section)
2. Send Email: Send email from an allowed address to your Val Town email address
3. Verify Email: Click the verification link sent to your email
4. View Blog: Visit your backend HTTP val URL after verification
5. RSS Feed: Access /rss for syndication
6. Individual Posts: Visit /post/[slug]

See SETUP.md for detailed setup instructions and ACTIVITYPUB.md for ActivityPub federation details.

• ALLOWED_EMAIL_ADDRESSES - Comma-separated list of allowed email addresses (required for email publishing)
• BASE_URL - Your blog's base URL (e.g., https://myblog.com or just myblog.com) - Required for custom domains and ActivityPub federation
• UPLOAD_PASSWORD - Password required for image uploads (required to enable image upload functionality)

• WEBSUB_HUB_URL - WebSub hub URL
• ACTIVITYPUB_DOMAIN - Domain for ActivityPub federation (deprecated - use BASE_URL instead)
• ATPROTO_HANDLE - AT Protocol handle
• ATPROTO_PASSWORD - AT Protocol app password
• ADMIN_PASSWORD - Admin password for advanced features (falls back to UPLOAD_PASSWORD if not set)

For proper ActivityPub federation with HTTP signatures (recommended for production):

• ACTIVITYPUB_PUBLIC_KEY - RSA public key in PEM format
• ACTIVITYPUB_PRIVATE_KEY - RSA private key in PEM format

To generate these keys:

1. Visit /generate-keys.ts (your key generator val)
2. Copy the generated keys to your environment variables
3. Restart your val

Without these keys, the system will generate temporary keys that change on restart, which may cause federation issues.

The platform includes several testing and debugging endpoints that are only accessible in development mode for security.

Set one of these environment variables to enable testing endpoints:

• NODE_ENV=development
• DEV_MODE=true
• ENABLE_TEST_ENDPOINTS=true

When development mode is enabled, you can access:

• /test-activitypub.ts - Test ActivityPub and WebFinger endpoints
• /test-publish.ts - Create a test blog post
• /test-follow.ts - Test Follow activity processing
• /test-verification.ts - Test email verification flow
• /test-http-signatures.ts - Test HTTP signatures implementation
• /test-activitypub-inbox.ts - Test ActivityPub inbox functionality
• /test-activitypub-delivery.ts - Test ActivityPub delivery with HTTP signatures
• /debug-config.ts - Debug email security configuration
• /debug-signatures.ts - Debug HTTP signatures in detail
• /generate-keys.ts - Generate RSA keys for ActivityPub

In production (when development mode is disabled), all test endpoints return a 404 response, ensuring your production environment remains secure while allowing full testing capabilities during development.

To use a custom domain with ActivityPub federation:

1. Set up your custom domain in Val Town (see Val Town documentation)
2. Set the BASE_URL environment variable to your custom domain:
   • BASE_URL=https://yourdomain.com (with protocol)
   • OR BASE_URL=yourdomain.com (protocol will be assumed as https)
3. Test ActivityPub discovery by visiting https://yourdomain.com/.well-known/webfinger?resource=acct:blog@yourdomain.com

Without BASE_URL set, the system will use the default Val Town URL for ActivityPub federation.

• GET / - Main blog interface (with ActivityPub Link header)
• GET /post/:slug - Individual post page (supports content negotiation for ActivityPub)
• GET /edit - Post editing interface (admin only) ✅
• GET /upload - Image upload interface ✅
• GET /images/:filename - Serve uploaded images ✅
• GET /rss - RSS 2.0 feed
• GET /api/posts - JSON API for posts
• GET /api/posts/:slug - JSON API for single post
• PUT /api/posts/:slug - Update a post (admin only) ✅
• DELETE /api/posts/:slug - Delete a post (admin only) ✅
• POST /api/images/upload - Upload image endpoint ✅
• GET /api/posts/:slug/images - Get images for a specific post ✅
• GET /api/images/user/:email - Get images uploaded by a user ✅
• GET /api/images - Get all images (admin endpoint) ✅
• DELETE /api/images/:filename - Delete an image ✅
• GET /websub - WebSub subscription endpoint
• GET /.well-known/webfinger - WebFinger discovery for ActivityPub ✅
• GET /actor - ActivityPub actor document with rich metadata ✅
• GET /outbox - ActivityPub outbox (paginated published activities) ✅
• GET /outbox?page=N - Paginated outbox pages ✅
• GET /followers - ActivityPub followers collection (with pagination support) ✅
• GET /followers-list - Human-readable followers page ✅
• GET /api/followers - JSON API for followers list ✅
• GET /following - ActivityPub following collection ✅
• POST /inbox - ActivityPub inbox (processes Follow, Like, Announce, Undo) ✅
• GET /api/posts/:slug/activities - Get activity counts (likes, shares, replies) ✅
• GET /verify-email - Email verification endpoint ✅
• GET /health - Health check

Only emails from pre-configured addresses can publish posts. Configure via environment variable:

ALLOWED_EMAIL_ADDRESSES=user1@example.com,user2@example.com,admin@myblog.com

To prevent spoofing, all emails go through a verification process:

1. Email Received: Email is stored as a draft (not published)
2. Verification Sent: Automated verification email sent to sender
3. User Clicks Link: Sender clicks verification link in email
4. Post Published: After verification, post is published and syndicated

• Anti-spoofing: Prevents unauthorized users from publishing posts
• Email confirmation: Ensures the sender actually sent the email
• Time-limited: Verification links expire after 24 hours
• Automatic cleanup: Expired drafts are automatically removed

The platform includes comprehensive image storage capabilities with advanced email attachment processing.

The platform provides a secure web interface for editing and deleting posts with proper authentication.

1. Visit the Edit Page: Go to /edit on your blog
2. Admin Authentication: Enter your admin password (ADMIN_PASSWORD or UPLOAD_PASSWORD)
3. Load Post: Enter the post slug and click "Load Post"
4. Edit Content: Use the tabbed interface to edit content and preview changes
5. Save Changes: Click "Save Changes" to update the post

• 🔒 Secure Authentication: Requires admin password to access
• 📝 Rich Editor: Tabbed interface with edit and preview modes
• 🎨 Content Type Support: Switch between HTML and plain text
• 👁️ Live Preview: Real-time preview of your changes
• 💾 Auto-save: Save changes with a single click
• 🗑️ Post Deletion: Secure post deletion with confirmation
• 🔗 Direct Links: Edit links on individual post pages with pre-filled slugs

• Password Protection: All editing operations require admin authentication
• Input Validation: Proper validation of all form inputs
• XSS Prevention: Content is properly escaped and sanitized
• CSRF Protection: Operations are protected against cross-site request forgery
• Audit Trail: All edit and delete operations are logged

// Update a post (requires admin password)
const response = await fetch(`/api/posts/${slug}`, {
  method: 'PUT',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    password: 'your-admin-password',
    title: 'Updated Title',
    content: 'Updated content',
    content_type: 'html'
  })
});

// Delete a post (requires admin password)
const response = await fetch(`/api/posts/${slug}?password=your-admin-password`, {
  method: 'DELETE'
});

• From Post Pages: Click the "✏️ Edit" button on any post page
• Pre-filled Forms: Post slug is automatically filled when accessing from post pages
• Direct URLs: Use /edit?slug=your-post-slug for direct access

The platform includes comprehensive image storage capabilities with advanced email attachment processing.

1. Web Interface: Visit /upload (requires UPLOAD_PASSWORD) to upload images via drag-and-drop interface
2. Email Attachments: Images attached to blog post emails are automatically processed and stored

The system handles two types of email images:

• Content-ID References: cid:filename.jpg references are automatically converted to proper URLs
• Broken Image Tags: Empty or invalid src attributes are fixed
• Multiple Formats: Supports various email client reference patterns
• Automatic Replacement: Images are seamlessly integrated into post content

• Unreferenced Attachments: Images attached but not referenced in email content are automatically added
• Dedicated Section: Unreferenced images appear in a styled "Attachments" section
• Proper Styling: Images are displayed with responsive styling and captions

• JPEG/JPG
• PNG
• GIF
• WebP
• SVG

File Size Limit: 5MB per image

• Filename Escaping: Special characters in filenames are properly handled
• URL Generation: Automatic generation of proper image URLs with base domain
• Alt Text Preservation: Original alt text and filenames are preserved
• Responsive Styling: Images are automatically styled for responsive display
• Error Handling: Graceful handling of corrupted or invalid images

• Password Protection: Upload interface protected by UPLOAD_PASSWORD environment variable
• Automatic Processing: Email attachments are automatically extracted and stored
• Content Reference Replacement: Image references in email content are automatically updated to use stored URLs
• Metadata Storage: Original filename, MIME type, file size, alt text, and post associations
• Secure Access: Password-protected upload system prevents unauthorized access
• Blob Storage: Images stored using Val Town's blob storage with unique filenames
• URL Generation: Clean /images/filename URLs for serving images

// Upload an image (requires password)
const formData = new FormData();
formData.append('image', file);
formData.append('password', 'your-upload-password');
formData.append('email', 'your-email@example.com');
formData.append('altText', 'Description of image');
formData.append('postSlug', 'my-blog-post'); // optional

const response = await fetch('/api/images/upload', {
  method: 'POST',
  body: formData
});

// Get images for a post (no password required)
const images = await fetch('/api/posts/my-post-slug/images').then(r => r.json());

// Get images by user (requires password)
const userImages = await fetch('/api/images/user/user@example.com?password=your-upload-password').then(r => r.json());

// Get all images (requires password)
const allImages = await fetch('/api/images?password=your-upload-password&limit=50').then(r => r.json());

When you send an email with image attachments:

1. Automatic Detection: System identifies image attachments by MIME type
2. Storage: Images are stored with unique filenames in blob storage
3. Database Records: Metadata is saved linking images to the post
4. Content Updates: Email content is updated to reference stored image URLs
5. Reference Replacement: Common patterns like cid:image.jpg are replaced with proper URLs

Example email with attachment:

To: your-blog@val.town
From: author@example.com
Subject: My Post with Images
Attachments: photo.jpg, diagram.png

<p>Check out this photo:</p>
<img src="cid:photo.jpg" alt="My photo" />
<p>And this diagram: [diagram.png]</p>

After processing, the content becomes:

<p>Check out this photo:</p>
<img src="/images/1234567890-abc123-photo.jpg" alt="My photo" />
<p>And this diagram: ![diagram.png](/images/1234567890-def456-diagram.png)</p>

Use /test-publish.ts to create sample posts for testing.

Send an email like this:

To: your-email-val@val.town
From: allowed-user@example.com  (must be in ALLOWED_EMAIL_ADDRESSES)
Subject: My Amazing Blog Post
Body: <h2>Hello World!</h2><p>This post was published via email!</p>

The process will be:

1. Email received and stored as draft
2. Verification email sent to allowed-user@example.com
3. User clicks verification link
4. Post published with:
   • Title: "My Amazing Blog Post"
   • Slug: "my-amazing-blog-post"
   • Content: Rendered HTML
   • Author: Extracted from email address

• Edit HTML generation functions in /backend/index.ts
• Modify CSS styles in the getCustomCSS() function
• Update branding in HTML templates
• Configure federation services via environment variables

Posts are automatically syndicated to:

• RSS feed (always enabled)
• WebSub subscribers (if configured)
• ActivityPub followers (with full interaction support) ✅
• AT Protocol/Bluesky (if configured)

Your blog is now fully federated with ActivityPub! Users can:

• Follow your blog from Mastodon, Pleroma, and other ActivityPub platforms
• Like your blog posts (shows ❤️ count on posts)
• Share/Boost your posts (shows 🔄 count on posts)
• Reply to your posts (shows 💬 count on posts)
• Preview posts directly in Mastodon timeline with proper formatting

Discovery formats:

• WebFinger: @blog@your-domain.com
• Direct actor URL: https://your-domain.com/actor

Configuration for custom domains:

• Set BASE_URL=https://your-custom-domain.com in your environment variables
• This ensures all ActivityPub URLs use your custom domain instead of the default Val Town URL

Enhanced ActivityPub Features:

• ✅ Paginated Outbox: Posts are served with proper pagination for better performance
• ✅ Rich Post Previews: Posts display with titles, summaries, and full content in Mastodon
• ✅ Content Negotiation: Individual posts serve both HTML and ActivityPub JSON based on Accept headers
• ✅ Profile Metadata: Actor profile includes avatar, header image, and custom fields
• ✅ Link Discovery: Proper HTTP Link headers for ActivityPub discovery
• ✅ Post Permalinks: Each post has its own ActivityPub Note endpoint

Real-time interaction tracking:

• All likes, shares, and replies are stored and displayed on individual post pages
• Follower count is maintained and accurate
• Full ActivityPub inbox processing for Follow/Unfollow activities

Example: If your blog is at myblog.com (with BASE_URL=https://myblog.com), users can follow @blog@myblog.com from their Mastodon client and see your posts with rich previews in their timeline!

Ready to blog via email? Send your first post now! 📧✨