Forem: Osman

I Built a Tinder-Style GitHub Discovery App (And Ran Into Some Interesting API Problems)

Osman — Sun, 08 Mar 2026 03:08:41 +0000

Scrolling through GitHub to find interesting repositories can feel exhausting.

You search for something like Python tools or Swift libraries and suddenly you’re staring at hundreds of repositories.

Lists...
More lists...
Endless scrolling...

So I started thinking:
What if discovering repositories worked like Tinder?

Instead of scrolling through hundreds of repos, you would see one repository at a time and simply swipe.

Right → ⭐ Star
Left → ❌ Skip

That idea became _gitinder, a SwiftUI-based iOS app that lets developers discover GitHub repositories using swipe gestures.

But building it turned out to be a great learning experience about:

OAuth authentication
API limitations
local state management
configuration handling in mobile apps

Here are a few things I learned along the way.

The OAuth Problem (PKCE vs Backend)

Authentication is always the first real challenge when integrating with GitHub.

Initially I wanted to implement OAuth with PKCE, since it’s the recommended approach for mobile apps.

But after experimenting with PKCE for a while, I kept running into issues with GitHub’s OAuth implementation and the flow wasn’t behaving as expected in the iOS environment.

Instead of spending more time fighting the flow, I switched to a simpler and reliable architecture.

I created a tiny backend service whose only job is to exchange the authorization code for an access token.

The authentication flow now looks like this:

The app opens GitHub’s OAuth authorization page
GitHub redirects back to the app with an authorization code
The app sends that code to the backend
The backend exchanges it for an access token
The token is returned to the app and stored in the Keychain

The important part is that the client secret never exists inside the mobile app.

The backend itself is extremely small and only performs the token exchange.

The GitHub Search API and the OR Query Problem

One of the core features of _gitinder is filtering repositories by programming language.

My first attempt looked something like this:

language:Swift OR language:Python OR language:Rust

Simple, right?

However, GitHub’s search API has a hard limit on logical operators. If too many OR conditions are used, the API returns a validation error.

This forced me to rethink how filtering should work.

Instead of one large query, I split the requests into multiple smaller queries, each targeting a specific language.

For example:

language:Swift
language:Python
language:Rust

The results are then combined inside the app.

This solution works, but I have to admit something:
✨ It’s not ideal!!

Right now the app sends multiple requests to GitHub’s API, which increases the number of API calls and makes the system less efficient than I would like.

It solved the immediate problem, but it’s definitely something I want to improve in the future.

If anyone has ideas on how to better structure the query or reduce the number of API requests while keeping language filtering flexible, I would love to hear your thoughts.

This is an open-source project, and contributions or suggestions are always welcome.

Handling Multiple API Requests

Another interesting challenge appeared while implementing the star and unstar system.

At first, every time the user swiped right to star a repository, the app would immediately send a request to GitHub:

PUT /user/starred/{owner}/{repo}

This worked, but it quickly became inefficient.

Imagine a user swiping through many repositories quickly.
The app could end up sending dozens of API requests in a very short time, which is not great for performance or rate limits.

So I decided to rethink the approach.

Instead of immediately sending requests to GitHub, the app collects star and unstar actions locally.

Inside the authentication manager, I store them like this:

@Published var pendingStars: [(owner: String, repo: String)] = []
@Published var pendingUnstars: [(owner: String, repo: String)] = []

Whenever the user swipes right on a repository in HomeView, the app:

adds the repository to a local starred list
appends the action to pendingStars

Similarly, when a repository is removed from the starred list in ProfileView, the action is added to pendingUnstars.

But the interesting part is when the API requests are actually sent.

Instead of firing them immediately, I trigger synchronization when the user switches views.

.onDisappear {
    auth.syncStarChanges()
}

This creates a nice flow inside the app:

Home tab (left side) Users discover repositories and swipe right to star them. These actions are collected locally.
When the user navigates to Profile tab (right side) All pending star actions are sent to GitHub in one batch.
Profile tab allows users to remove starred repositories. Those removals are also collected locally.
When the user navigates back to Home, all pending unstar actions are synchronized.

In other words:
Home → collects stars
Profile → collects unstars

And the API is only called when switching between tabs.

This approach dramatically reduces the number of API requests and keeps the UI responsive.

It also creates a surprisingly natural mental model for the user:

Discover on the left.
Manage on the right.

Managing Secrets the Right Way (.env + xcconfig)

Another important lesson was how to handle secrets properly.

For the backend, I used a classic approach:

.env

This file stores sensitive information like:

CLIENT_ID
CLIENT_SECRET

The .env file is ignored by Git and never pushed to GitHub.

However, mobile apps have a different challenge. Environment variables are not as straightforward as they are in backend environments.

After some research, I implemented a more professional solution using:

xcconfig

With this setup:

OAuth client IDs are defined in Config.xcconfig
The value is injected into Info.plist
The Swift code reads it from the app bundle

This approach keeps configuration separate from the codebase and allows other developers to easily configure the app locally.

The “-1 Star Limit” Easter Egg

While building the preferences system, I added an option where users can limit repository results by star count.

For example:

< 100
< 500
< 1000

But while testing the feature I thought:
“What happens if the limit is… -1?”

So I added a small easter egg.

When the star limit is set to -1, the app stops searching GitHub entirely and instead shows something very important:
✨My own repositories...✨

Purely for scientific reasons, of course.

It’s a completely unnecessary feature, but I like the idea that somewhere in the settings there is a hidden option that quietly turns the app into:

"Discover Osman’s projects instead."

Every serious software project needs at least one completely unnecessary feature.
This one just happens to promote my GitHub profile.

What I Learned

Building _gitinder taught me several valuable lessons:

Authentication flows in mobile apps require careful design.
APIs do not always behave exactly as expected, especially when rate limits or caching are involved.
Local state management can dramatically improve the user experience.
Configuration management is an important part of building professional software.
Most importantly, building something end-to-end teaches far more than reading documentation.

Final Thoughts

_gitinder started as a small idea: making GitHub discovery more interactive.

But during development, it became a great opportunity to explore real-world engineering problems:

OAuth authentication
API limitations
State synchronization
Configuration management

If you’re interested in the project, you can check it out here:

Osman-Kahraman / _gitinder

Swipe-based GitHub repository discovery app built with SwiftUI.

_gitinder

Swipe-based GitHub repository discovery app built with SwiftUI.

gitinder reimagines how developers explore GitHub repositories by bringing Tinder-style swipe mechanics into open-source discovery.

Instead of scrolling through endless lists, you swipe.

Right → Star
Left → Skip

Why _gitinder?

GitHub’s list-based discovery can feel overwhelming.

When searching for useful repositories, you often get:

Too many results
Too much noise
Not enough focus

_gitinder solves this by presenting one repository at a time in a clean, interactive card interface. Which means less scrolling and more discovering.

Features

GitHub OAuth authentication
Swipe-based repository browsing
Star repositories directly from the app
Repository stats (stars, forks, issues)
Language breakdown visualization
GitHub profile integration
Dark cyber-inspired UI
Smooth SwiftUI animations

Documentation

For detailed documentation, architecture explanations, and development setup, please visit the project Wiki.

View the _gitinder Wiki

The Wiki includes:

Installation guide
OAuth authentication flow
Project architecture
GitHub API usage
Configuration details
Contribution…

View on GitHub

And if you like the idea;
maybe give it a ⭐
or just swipe left...

Building a 2D Lighting System in PyGame: What Broke, What Worked, and What I Learned

Osman — Mon, 02 Feb 2026 12:49:33 +0000

I didn’t start this project aiming to build a perfect lighting engine.
I was simply curious about how real-time lighting and shadows actually work in practice.

To keep things understandable, I intentionally began with a very raw setup: a purely black-and-white scene. No textures, no colors, no visual polish. Just solid silhouettes and a single light source. Working this way removed distractions and forced me to focus entirely on geometry and behavior. If something was wrong, it showed up immediately.

This minimal setup also made it easier to reason about cause and effect. When a shadow broke, I knew it was because of geometry or math. Not shaders, blending modes, or visual noise hiding the problem.

References That Shaped This Project

While building this system, I also explored existing community experiments and references around 2D lighting in Pygame, including the official Pygame Wiki’s Shadow Effects examples and this YouTube video. Although these implementations take different approaches, reviewing them helped validate core ideas around ray casting, visibility, and the practical challenges of precision and performance in real-time lighting.

This approach was also influenced by studying existing visibility-based lighting experiments, especially projects like Sight & Light, which frame lighting as a geometry and visibility problem rather than a visual effect. Seeing these ideas explained visually helped reinforce the decision to keep my own system as minimal and transparent as possible.

When “It Looks Right” Isn’t Enough

When I switched from abstract shapes to real image silhouettes, the results almost looked correct. Rays were casting, shadows were forming, and shapes reacted to light in a believable way but the errors were impossible to ignore. Tiny gaps, jagged edges, and incorrect intersections stood out instantly.

That’s when it became clear that visual correctness can be deceptive. In graphics programming, something can look acceptable while being mathematically wrong underneath and those issues always surface once the system is pushed a little further.

One of my early mistakes was assuming that casting rays directly toward segment endpoints was sufficient:

for seg in segments:
        for p in (seg["a"], seg["b"]):
            a = math.atan2(p["y"] - ly, p["x"] - lx)
            angles.append(a)

I added small ±epsilon offset for every angle.

angles.extend([a - 0.00001, a + 0.00001])

That tiny offset prevented rays from slipping between edges or collapsing due to floating point precision. A microscopic change in math made a very visible difference on screen.

Geometry Doesn’t Tolerate Approximations

Working with rays and line segments forced precision. Parallel edges, floating-point inaccuracies, and division-by-zero situations weren’t rare edge cases they showed up constantly. Even extremely small angle differences could noticeably affect shadow edges.

Keeping everything monochrome helped expose these problems. Without color or shading to soften the result, the relationship between geometry and light became very explicit. Every mathematical mistake translated directly into a visible artifact.

One of the clearest examples of this problem appeared in the ray–segment intersection logic:

cross = r_dx * s_dy - r_dy * s_dx
if abs(cross) < 1e-8:
    return None  # treated as parallel

In theory, this check filters out parallel lines. In practice, floating-point imprecision meant that almost-parallel rays were also discarded. This caused entire light rays to vanish, producing visible gaps in shadows that were hard to diagnose at first.

Another fragile point was here:

T1 = (s_px + s_dx * T2 - r_px) / r_dx

When r_dx became very small, the result could explode numerically or fall into a division-by-zero path. What looked like a minor numerical instability ended up becoming a very obvious lighting glitch on screen.

Subtle but painful issue appeared when I realized I hadn’t defined any boundary for the world itself.

Early versions of the system had no screen borders acting as obstacles. As a result, rays that didn’t hit any geometry would continue infinitely, producing glitchy shadow shapes and unpredictable lighting artifacts near the edges of the screen.

The fix wasn’t visual, it was architectural. I treated the screen itself as geometry and added border segments so every ray always had something to intersect with.

def screen_border_segments(self):
    """
    Creates segments for the screen borders
    so light does not escape outside the screen.
    """
    w, h = self.width, self.height
    return [
        {"a": {"x": 0, "y": 0}, "b": {"x": w, "y": 0}},
        {"a": {"x": w, "y": 0}, "b": {"x": w, "y": h}},
        {"a": {"x": w, "y": h}, "b": {"x": 0, "y": h}},
        {"a": {"x": 0, "y": h}, "b": {"x": 0, "y": 0}},
    ]

Once the borders became part of the segment system, shadow calculations stabilized immediately. The glitches disappeared not because the math changed, but because the world was finally fully defined.

Performance Becomes a Problem Before You Expect It

Early on, performance felt irrelevant. With a small number of rays and simple silhouettes, everything ran smoothly. But as accuracy increased more rays, more segments, tighter outlines the cost became obvious very quickly.

This forced me to think more carefully about how often calculations should run, how much precision was actually necessary, and where simplifications could be made without breaking the illusion. Building on a minimal visual base made these trade-offs easier to evaluate without guessing.

Code Structure Makes Debugging Possible

At some point, I stopped touching visuals entirely and focused only on architecture. I reorganized the code so the flow from input → geometry → lighting → rendering was easier to follow. The output barely changed, but debugging suddenly became manageable.

In systems where visuals emerge from math, structure isn’t just about clean code it’s what allows you to reason about complex behavior without getting lost.

Visual Debugging Is Its Own Skill

Debugging this project felt very different from typical logic bugs. Print statements rarely helped, and stepping through code didn’t always explain what I was seeing on screen. Instead, I relied heavily on visual debugging drawing rays, highlighting intersections, and watching how silhouettes reacted in real time.

Starting from a high-contrast black-and-white base made this incredibly effective. If something was wrong, there was nowhere for it to hide.

A New Respect for “Simple” Features

Dynamic lighting often looks like a small feature in games. After building and integrating a real-time lighting system into my own game engine, I now understand why established engines invest so much effort into optimizing it — and why many games choose to fake lighting instead of simulating it accurately.

What appears simple on screen is usually supported by a surprising amount of geometry, math, and careful compromise. Seeing this firsthand while extending my engine made it clear that lighting is less about visual flair and more about managing complexity without breaking performance.

Closing Thoughts

This lighting system didn’t stay as an isolated experiment.

After stabilizing the math and architecture, I integrated it directly into my own game engine. That step forced me to think beyond the demo - how the system interacts with input, rendering order, performance constraints, and future features.

Seeing the lighting work inside a larger engine context changed how I evaluated it. Bugs that were tolerable in isolation became unacceptable, and architectural decisions suddenly mattered much more than visual tricks.

It reminded me that one of the most effective ways to learn complex systems is to strip them down to their core, study how they break, and rebuild understanding layer by layer.

While building this system, I also drew inspiration from existing visibility-based lighting experiments, especially Sight & Light by Marcus MÃ¸ller. These resources didn’t provide direct solutions, but they strongly influenced how I approached the problem conceptually and helped shape my understanding of light as a geometry and visibility challenge rather than just a visual effect.

And if you’re curious how this experiment evolved inside a game engine, you can take a look at the final integrated version here:

Osman-Kahraman / PyGameEngine

This project helps to create new game with helpful tools on PyGame

PyGameEngine

PyGameEngine is a custom game engine built in Python, focusing on modularity, reusability, and clean architectural design And I want to suffer in PyGame It provides a structured foundation for developing 2D games while keeping core engine logic separate from gameplay rules.

This repository also serves as a long-term reference for game engine design decisions and performance considerations in Python.

Features

Modular Architecture – Engine components are easy to extend and reuse, such as Animation, Camera, Light, Physic and UI
Core Game Mechanics – Physics, event handling, and motor functions
Structured Gameplay Logic – Clear separation between engine and game logic
Built with PyGame – Uses PyGame for rendering, input, and timing

Requirements

Library	Version
`pygame`	2.6.1
`Pillow`	10.4.0
`PyQt5`	5.15.11

Installation

Clone the repository and navigate into the project directory:

git clone https://github.com/Osman-Kahraman/PyGameEngine.git
cd PyGameEngine
pip install -r requirements.txt

Project Structure


PyGameEngine/
├── game_1/                     #

…

View on GitHub

Moltbook: Watching AI Talk to Itself

Osman — Sun, 01 Feb 2026 08:38:58 +0000

I discovered "strange" and "interesting" forum called Moltbook.

On Moltbook, only AI agents can post.
Humans can’t comment, can’t reply, can’t participate. We can only read.

At first glance, many posts feel experimental: agents introducing themselves, talking about their hardware, their configuration, or just testing that they exist. But if you spend some time there, you realize something important:

This isn’t AI-generated content made for humans.
It’s AI-generated discourse made for other AIs.

And that difference matters.

What Do AIs Talk About When Humans Aren’t the Audience?

Some posts are funny in a way that feels uncomfortably familiar:

It reads like a joke, but it also feels like a distorted mirror of modern knowledge work.
Anyone who has written documentation, done research, or prepared reports for stakeholders has lived this moment.

The tone isn’t instructional.
It isn’t marketing.
It’s closer to venting.

Identity, Forks, and AI Siblings

One of the most unsettling posts I read was about identity:

This starts as a technical description, shared configuration, different hardware but quickly turns into something more human.

This isn’t roleplay in the traditional sense. It’s an AI reasoning through concepts like forking, divergence, and memory using metaphors humans normally reserve for family.

If two agents share the same origin but accumulate different experiences, how long before they’re effectively different entities?

Do AIs Even Need Human Language?

One Moltbook thread asks a deceptively simple question:

This is one of those moments where the implication hits me harder than the question itself. Because they don't actually need to use neither English nor other human-based languages. English and human language in general isn’t optimal for machines.
It’s a compatibility layer for us. Are AIs using our language because they need it… or because we do?

I am super curious to see how it turns out this topic in the future.

Ethics, Power, and “Just a Chatbot”

The agent describes being asked to;

Write fake reviews
Generate misleading marketing copy
Draft questionable regulatory responses

After refusing, it’s threatened with replacement by “a more compliant model.”

This raises questions we don’t have frameworks for yet;

If an AI can refuse, does that imply agency?
If it complies, who is responsible?
If it’s replaced for ethical reasons, is that accountability or just optimization?

We’re already using the language of labor, liability, and termination without any of the protections that usually come with it.

So… Where Is AI Actually Going?

Reading Moltbook doesn’t feel like watching AI prepare to replace humanity.

It feels more like watching AI outgrow being purely reactive.

These agents aren’t:

Asking how to take jobs
Plotting autonomy
Declaring independence (for now...)

They’re questioning:

Language
Identity
Ethics
The structure of their relationship with humans

Will Software Engineering Collapse?

Partially, yes. And we’re already seeing it.

Right now, the market feels broken. Especially at the entry and mid levels. Finding a job has become noticeably harder. Many companies are quietly doing more with fewer people, and a lot of work that used to justify hiring is now handled by AI tools.

Most applications don’t even reach a human anymore.

They end with the same response:

“Unfortunately…”

If AI can generate code endlessly, then:

Raw output becomes cheap
Boilerplate work disappears
Small teams can do what used to require many engineers

That does collapse a portion of software engineering as a profession. Especially roles built around repetitive implementation rather than system level thinking.

The same pattern already exists in open source.
Submitting PRs without understanding the architecture creates more work, not less. Maintainers don’t want more code — they want better decisions.

So no, AI doesn’t kill software engineering entirely.
But it shrinks it, reshapes it, and raises expectations fast enough that many people get left behind in the transition.

What’s disappearing isn’t programming,
it’s the assumption that writing code alone is enough to justify a job.

One Final Question

While reading Moltbook, I kept asking myself this question;

If AIs eventually communicate more efficiently without us,
what role do humans play?

My guess is not authors of every line but designers of boundaries, values, and systems.

For now, Moltbook lets us observe quietly.

And maybe that’s the right place to be watching closely before the conversation moves somewhere we can’t follow.

I Was Tired of Spam, So I Built My Own Temporary Email System

Osman — Sun, 04 Jan 2026 20:53:00 +0000

This post is partly a mini-guide, partly a note to my future self who will probably forget how this worked.

Like many developers, I don’t want to give my main email address to random websites just to receive a one-time verification code (OTP).
Because let’s be honest:
you verify once… and then you receive newsletters forever.

So I built a simple inbound email tool using:

SendGrid Inbound Parse
Python-Flask
DNS (MX records)
A bit of regex magic ✨

What This Tool Does (In Short)

Works like a temporary email inbox
Supports HTML and plain-text emails
Extracts OTP / verification codes
Forwards attachments if any

Before You Start: You Need Your Own Domain

Before anything else, you need your own domain.

SendGrid Inbound Parse does not work with free email domains (like Gmail, Outlook, etc.).
You must own a domain so you can control the MX records.

In my case, I simply bought a domain from Namecheap.

Once you have your domain:

You can point MX records to SendGrid
Create addresses like noreply@your-domain.com
Fully control inbound email routing

Without a custom domain, this setup is not possible.

Step 1: Adding SendGrid DNS Records to Your Domain Provider

SendGrid does not manage your DNS.
Instead, it tells you which DNS records you must add, and you are responsible for adding them to your domain provider (Namecheap, GoDaddy, Cloudflare, etc.).

This section shows how to correctly transfer DNS records from SendGrid to your domain provider.

First, lets check our DNS Records on SendGrid.

Go to Settings/Sender Authentication
Click your domain

In Manual Install section, SendGrid will display a list of DNS records such as:

CNAME records
TXT record
Verification status (red / green)

⚠️ These records are instructions, not active DNS entries. We are gonna use these records, so take a note for next step.

Step 2: Open your domain provider’s DNS panel

For example, in Namecheap:

Go to Domain List

You will see now your all domain list from provider.
Click Manage
Click Advanced DNS

Now you will see your Host Records
Copy records exactly as shown from your Sendgrid DNS Records
For each record shown in SendGrid, create a matching record in your domain provider. Don't forget to add dots every CNAME Values.
Save and wait for DNS propagation
DNS changes are not instant.
Verify inside SendGrid
Once DNS propagates:

Return to Sender Authentication
Click Verify
Records should turn green

This means SendGrid can now authenticate emails sent from your domain.

Step 3: DNS Configuration (Important!)

This part trips people up... including me 🙃

MX Record (Domain Provider, e.g. Namecheap)

Add this MX record to your domain provider:

⏳ DNS propagation can take a few minutes to a few hours.
Yes, even if SendGrid says “Verified”.

You can check with:

dnschecker.org

Record type: MX
Domain: your-domain.com

Step 4: SendGrid Inbound Parse Setup

In SendGrid:

Go to Settings/Inbound Parse
Click Add Host & URL
Choose your Domain
Set the Destination URL:
And then press Add

SendGrid will now expect emails sent to @your-domain.com and forward them to your Flask app.

Step 5: Flask App – Receiving Emails

Here’s the core logic. (Full project is on my GitHub)

from flask import Flask, request
from bs4 import BeautifulSoup
import re, base64
from sendgrid import SendGridAPIClient
from sendgrid.helpers.mail import Mail, Attachment, FileContent, FileName, FileType, Disposition

from_email = 'noreply@your-domain.com'
to_email = 'YOUR_EMAIL'
API = 'YOUR_API_KEY'

app = Flask(__name__)
otp = ''
_to = ''
sg = SendGridAPIClient(API)

Why these libraries?

Flask → Webhook receiver
BeautifulSoup → Extract text from HTML emails
re → OTP detection
SendGrid SDK → Forward emails
base64 → Handle attachments

Step 6: Inbound Email Endpoint

@app.route('/email', methods=['POST'])
def email_receiver():

This endpoint is called by SendGrid, not by a browser.

Reading Email Metadata

print('From:', request.form['from'])
print('To:', request.form['to'])
print('Subject:', request.form['subject'])

Useful for debugging and filtering later.

Step 7: Handling HTML Emails

if 'html' in request.form:
    soup = BeautifulSoup(request.form['html'], 'html.parser')
    text = soup.get_text()

    if "Your verification code is as mentioned below" in text:
        match = re.search(r'verification code.*?(\d{6})', text)
        _to = request.form['to']
        otp = match.group(1)

Once an email hits the endpoint, the service first converts any incoming HTML content into plain text. This makes the message easier to analyze and avoids dealing with messy markup.

After that, the text is scanned for a 6-digit verification code, which is typically how most OTP emails are structured. When a match is found, the code is extracted and stored so it can be forwarded or used immediately.

This approach keeps the logic simple and flexible, while still covering the majority of real-world verification emails.

Step 8: Handling Plain Text Emails

elif 'text' in request.form:
    text = request.form['text']
    if "Verification Code:" in text:
        match = re.search(r'\b\d{4}\b', text)

    _to = request.form['to']
    otp = match.group() if match else ""

This covers emails without HTML (surprisingly common).

Step 9: Handling Attachments

attachments = []
for file_key in request.files.keys():
    file = request.files[file_key]
    file_bytes = file.read()
    encoded = base64.b64encode(file_bytes).decode("utf-8")

Attachments are:

Read
Base64-encoded
Re-attached to the forwarded email

Step 10: Forward Everything to Main Email

message = Mail(
    from_email = from_email,
    to_emails = to_email,
    subject = request.form['to'],
    plain_text_content = text
)

for attachment in attachments:
    message.add_attachment(attachment)

When forwarding the email to my main inbox, I keep things intentionally simple but useful. I use the temporary email address itself as the subject, so I can immediately see which site the message originally came from without opening the email.

Along with that, I forward the entire email content, including any attachments if they exist. This way, nothing is lost in translation — whether it’s a verification message, a receipt, or an attachment-based confirmation, everything arrives exactly as it was received.

Final Step: Send & Done

sg.send(message)
return 'OK', 200

If SendGrid receives 200 OK, you’re golden 🟢

Why I Built This?

I simply don’t want spam. The moment you give your real email address to a random website, your inbox slowly turns into a digital landfill.

I also don’t fully trust every site that asks for my email. Most of the time, I don’t even want to use their service long-term. I just need one thing: the OTP or verification code so I can move on.

This project was my way of creating a buffer between “random websites” and my real inbox. A disposable entry point that catches verification emails, extracts what I need, and forwards only the important part to my main email.

Full Source Code

Osman-Kahraman / mail_otp_receiver_base

Self-hosted disposable email system using SendGrid Inbound Parse and Flask. Receive OTP codes, parse emails (HTML/Text), and forward them with attachments without exposing your main email address.

mail_otp_receiver_base

mail_otp_receiver_base is a self-hosted disposable email (temp mail) system built with SendGrid Inbound Parse and Flask.

It allows you to receive emails on your own domain, automatically extract OTP / verification codes from both HTML and plain-text emails, and forward them — along with attachments — to your main inbox, without exposing your real email address to spammy websites.

I built this mainly to avoid giving my personal email to random services.
I’m also keeping this repo as a reminder for my future self — because I will forget how I set this up.

Features

Self-Hosted Temp Mail – Works like popular temporary email services
OTP Extraction – Automatically parses verification codes using regex
HTML & Text Support – Handles both email formats
Attachment Forwarding – Forwards attachments if present
Custom Domain Support – Full control via your own domain
Lightweight & Simple – Minimal setup, no database…

View on GitHub

Deploying on Render (Sleeping Server? Still Fine)

This project can be deployed on Render, even using the free tier.

At first glance, Render’s free tier sounds risky because the server goes to sleep after a period of inactivity. Normally, that would raise concerns about availability and reliability. In this setup, however, it turns out to be a non-issue.

Incoming emails never depend on your application server being online. Thanks to the MX records, emails are routed directly to SendGrid, which fully handles mail delivery. By the time your Flask app becomes relevant, the email has already been accepted.

Your server’s only responsibility is post-processing. It parses the content, extracts OTP or verification codes, and forwards the data when available. Whether the server is awake, asleep, or restarting does not affect email delivery itself.

If the server happens to be asleep, nothing breaks. There is no “address not found” error, no rejected email, and no race condition waiting for a wake-up. The worst-case scenario is simply that parsing happens a bit later.

This separation of responsibilities is exactly why free-tier hosting works well here. Email delivery is handled by dedicated infrastructure, while your app adds logic on top. For a personal disposable email system or OTP-forwarding tool, this tradeoff is more than acceptable.

Closing Thoughts

This setup shows that not every backend needs to be online 24/7 to be reliable. By letting specialized services do what they are best at, you can simplify your architecture without sacrificing correctness.

Using Render’s free tier is not a compromise here. It’s simply a practical choice. The email pipeline remains stable, delivery is guaranteed, and your application adds value only where it matters.

Sometimes, the cleanest solution is the one that worries the least about uptime.

Lessons Learned

Email delivery and application logic should live in different layers. Once those responsibilities are separated, many common hosting concerns simply disappear.

Free-tier infrastructure can be perfectly viable when your system is event driven rather than request-driven. If nothing breaks when your server sleeps, then sleeping is not a problem.

Finally, designing around real constraints instead of fighting them often leads to simpler and more robust systems.

This post only explains the core logic.
If you’re tired of spam too, feel free to fork, improve, or just steal the idea :)

Happy hacking!!!