I wanted a soft gate on my resume download. Not a paywall. Just an email field — enough friction to filter bots, enough signal to know who's interested. What started as a straightforward feature turned into a three-part lesson: stateless token signing, S3 public access, and email delivery mechanics.
Here's the full story.
The Feature
The flow I wanted:
- Visitor clicks "Download Resume" on the About page or Hero
- A modal asks for their email
- Backend validates the email (format + disposable domain check)
- A signed, time-limited link is emailed to them
- They click the link, the PDF opens
No database tokens. No cron jobs. No permanent S3 URLs floating around.
Part 1 — The Model and the Gate
The Resume Model
Resume follows the singleton pattern I already use for page headers — force pk=1 on every save, restrict add/delete in admin. One row, forever.
class Resume(models.Model):
pdf = models.FileField(upload_to="resume/", storage=private_resume_storage)
last_updated = models.DateField(default=date.today)
def save(self, *args, **kwargs):
self.pk = 1
super().save(*args, **kwargs)
ResumeDownloadRequest logs every email that requests a link — no tokens, no expiry columns, just a record of who asked and when.
class ResumeDownloadRequest(models.Model):
email = models.EmailField()
created_at = models.DateTimeField(auto_now_add=True)
unsubscribed = models.BooleanField(default=False)
class Meta:
ordering = ["-created_at"]
The unsubscribed flag is there for a future newsletter broadcast — when a new blog post goes out, skip anyone who opted out.
Blocking Disposable Emails
Before signing anything, the email is checked against a frozenset of ~70 known throwaway domains:
# core/validators.py
DISPOSABLE_EMAIL_DOMAINS: frozenset[str] = frozenset({
"mailinator.com",
"guerrillamail.com",
"yopmail.com",
"10minutemail.com",
"trashmail.com",
# ... ~70 total
})
def is_disposable_email(email: str) -> bool:
if "@" not in email:
return False
domain = email.rsplit("@", 1)[-1].lower().strip()
return domain in DISPOSABLE_EMAIL_DOMAINS
The serializer calls it in validate_email so DRF surfaces it as a standard field error.
Part 2 — django.core.signing.TimestampSigner
This is the part I hadn't used before. Django ships a signing module in django.core.signing that most people only know from cookies and sessions. It's a general-purpose tool for producing tamper-proof, time-limited strings — no database, no cache, no state anywhere.
from django.core import signing
signer = signing.TimestampSigner()
# Sign a payload — embeds the current timestamp
token = signer.sign_object({"pk": 1, "email": "user@example.com"})
# → "eyJwayI6MSwiZW1haWwiOiJ1c2VyQGV4YW1wbGUuY29tIn0:1wSd5Q:EHGb3ife..."
# Verify — raises SignatureExpired if older than max_age seconds
data = signer.unsign_object(token, max_age=900) # 15 minutes
# → {"pk": 1, "email": "user@example.com"}
The token is three colon-delimited parts: base64-encoded JSON payload, a base64-encoded timestamp, and an HMAC signature derived from SECRET_KEY. Tamper any part and it raises BadSignature. Wait too long and it raises SignatureExpired.
No rows inserted. No rows deleted. The server is completely stateless between the two requests.
The Two API Views
RESUME_TOKEN_MAX_AGE = 900 # 15 minutes
class ResumeRequestDownloadView(APIView):
authentication_classes = []
permission_classes = []
def post(self, request):
serializer = ResumeDownloadRequestSerializer(data=request.data)
if not serializer.is_valid():
return Response(
{"data": None, "message": "", "errors": serializer.errors},
status=status.HTTP_400_BAD_REQUEST,
)
email = serializer.validated_data["email"]
resume = Resume.objects.filter(pk=1).first()
if not resume:
return Response(
{"data": None, "message": "No resume available.", "errors": None},
status=status.HTTP_404_NOT_FOUND,
)
ResumeDownloadRequest.objects.create(email=email)
signer = signing.TimestampSigner()
token = signer.sign_object({"pk": resume.pk, "email": email})
download_path = reverse("api:resume-download") + f"?token={token}"
download_url = request.build_absolute_uri(download_path)
expires_minutes = RESUME_TOKEN_MAX_AGE // 60
self._send_download_email(email, download_url, expires_minutes)
return Response({
"data": None,
"message": f"Check your inbox — the link expires in {expires_minutes} minutes.",
"errors": None,
})
def _send_download_email(self, email, download_url, expires_minutes):
body = (
f"Hi there!\n\n"
f"Here's your link to download my resume:\n\n"
f"{download_url}\n\n"
f"This link expires in {expires_minutes} minutes.\n\n"
f"— Vicente Reyes\n"
f" https://vicentereyes.org"
)
with contextlib.suppress(Exception):
send_mail(
subject="Your resume download link",
message=body,
from_email=settings.DEFAULT_FROM_EMAIL,
recipient_list=[email],
fail_silently=True,
)
class ResumeDownloadView(APIView):
authentication_classes = []
permission_classes = []
def get(self, request):
token = request.query_params.get("token", "")
if not token:
return Response(
{"data": None, "message": "", "errors": {"token": ["This field is required."]}},
status=status.HTTP_400_BAD_REQUEST,
)
signer = signing.TimestampSigner()
data = None
with contextlib.suppress(signing.SignatureExpired, signing.BadSignature):
data = signer.unsign_object(token, max_age=RESUME_TOKEN_MAX_AGE)
if data is None:
try:
signer.unsign_object(token)
return Response(
{"data": None, "message": "Download link expired. Please request a new one.", "errors": None},
status=status.HTTP_410_GONE,
)
except signing.BadSignature:
return Response(
{"data": None, "message": "Invalid download token.", "errors": None},
status=status.HTTP_400_BAD_REQUEST,
)
resume = Resume.objects.filter(pk=data.get("pk")).first()
if not resume or not resume.pdf:
return Response(
{"data": None, "message": "Resume not found.", "errors": None},
status=status.HTTP_404_NOT_FOUND,
)
return HttpResponseRedirect(resume.pdf.url)
The expired-vs-tampered distinction matters: 410 Gone tells the frontend "the link was real but timed out, ask again." 400 means the token is garbage. Different messages, different user actions.
Part 3 — The S3 Bypass
I shipped it. It worked. Then I opened the S3 URL directly:
https://bucket.s3.amazonaws.com/media/resume/Vicente_Reyes_Resume.pdf
The PDF downloaded. No token, no email, no gate.
What Went Wrong
Two settings in production.py:
AWS_QUERYSTRING_AUTH = False # plain URLs, no signed query strings
AWS_DEFAULT_ACL = None # objects inherit bucket ACL → public-read
resume.pdf.url was returning a permanent, unauthenticated S3 URL. The gate was checking ID at the front door while the back window was wide open.
The Fix: Per-Field Private Storage
Changing AWS_QUERYSTRING_AUTH globally would break every other media file — blog covers, project screenshots, testimonial avatars — all meant to be public. The right scope is narrower: only the resume field needs private storage.
django-storages supports this through custom storage classes. Pass a callable to FileField's storage parameter and Django calls it at runtime to get the storage instance.
# core/storages.py
from django.conf import settings
from django.core.files.storage import FileSystemStorage
from storages.backends.s3boto3 import S3Boto3Storage
def private_resume_storage():
if getattr(settings, "AWS_STORAGE_BUCKET_NAME", None):
return S3Boto3Storage(
location="media",
default_acl="private",
querystring_auth=True,
querystring_expire=120, # presigned URL valid for 2 minutes
custom_domain=None, # presigned URLs need the real S3 endpoint
file_overwrite=False,
)
return FileSystemStorage()
# models.py
class Resume(models.Model):
pdf = models.FileField(upload_to="resume/", storage=private_resume_storage)
Now resume.pdf.url returns a presigned URL:
https://bucket.s3.amazonaws.com/media/resume/filename.pdf
?X-Amz-Algorithm=AWS4-HMAC-SHA256
&X-Amz-Credential=...
&X-Amz-Expires=120
&X-Amz-Signature=...
Valid for 120 seconds. The direct URL without the signature returns a 403. Sharing the URL or bookmarking it is pointless.
Why custom_domain=None
The production config has AWS_S3_CUSTOM_DOMAIN set. Custom domains don't support AWS Signature v4 query parameters — the presigned URL would be malformed. Setting custom_domain=None on the private storage instance forces django-storages to use the real S3 endpoint for that field only.
The Migration Surprise
Switching the storage callable requires a migration even though no columns change. Django records the storage class in migration state, so changing it from default to a callable produces a ~ Alter field pdf on resume migration. It's a no-op at the database level but Django needs it for consistency.
Part 4 — Email-First, Not Token-First
The original frontend flow returned the token in the API response and called window.open(downloadUrl, '_blank') immediately. The PDF opened before the user even checked their email.
The problem: someone could submit any email address, get the immediate download in their browser, and the link would go to whoever owned that inbox. The email was a log entry, not a gate.
Switching to email-first fixes it. The token is built server-side, put in the email body, and never returned to the frontend:
# Before
return Response({"data": {"token": token}, ...})
# After
self._send_download_email(email, download_url, expires_minutes)
return Response({"data": None, "message": "Check your inbox...", ...})
The frontend modal now shows a confirmation state instead of opening a new tab:
{sent ? (
<div className="text-center space-y-4">
<CheckCircle size={48} className="text-neo-green" />
<h2 className="text-2xl font-black uppercase">Check Your Inbox</h2>
<p className="font-medium opacity-80">
A download link has been sent to <span className="font-black">{email}</span>.
It expires in <span className="font-black">15 minutes</span>.
</p>
<Button variant="dark" size="md" onClick={onClose} fullWidth>Done</Button>
</div>
) : (
// ... form
)}
Part 5 — The Sender Name
First real email came in showing Portfolio Backend V2 as the sender. Not ideal.
The display name in From: headers comes from DEFAULT_FROM_EMAIL. It was hardcoded in the settings default:
# Before
DEFAULT_FROM_EMAIL = env(
"DJANGO_DEFAULT_FROM_EMAIL",
default="Portfolio Backend V2 <noreply@vicentereyes.org>",
)
# After
DEFAULT_FROM_EMAIL = env(
"DJANGO_DEFAULT_FROM_EMAIL",
default="Vicente Reyes <noreply@vicentereyes.org>",
)
One-line fix. The env var takes precedence if set on the server, so updating the default in code is just the fallback.
The Full Stack at a Glance
Browser Django S3
│ │ │
│ POST /api/resume/ │ │
│ request-download/ │ │
│ { email } │ │
│ ─────────────────────────► │ │
│ │ validate email │
│ │ block disposable domains │
│ │ log ResumeDownloadRequest │
│ │ TimestampSigner.sign() │
│ │ build_absolute_uri() │
│ │ send_mail() ──────────────────► inbox
│ ◄───────────────────────── │ │
│ { message: "Check │ │
│ your inbox" } │ │
│ │ │
│ [user clicks email link] │ │
│ │ │
│ GET /api/resume/download/ │ │
│ ?token=<signed> │ │
│ ─────────────────────────► │ │
│ │ verify token (15 min) │
│ │ resume.pdf.url ──────────► presigned URL
│ │ │ (120 sec)
│ ◄───────────────────────── │ │
│ 302 → presigned URL │ │
│ │ │
│ GET presigned URL ─────────────────────────────────► │
│ ◄───────────────────────────────────────────────── PDF│
What I'd Do Differently
Rate-limit the POST endpoint. Right now someone can hammer POST /api/resume/request-download/ with valid emails and flood inboxes. A simple per-IP throttle class on the view would fix it.
Consider Celery for the email send. send_mail in the request/response cycle means the API response waits for the SMTP round trip. On Mailgun it's fast, but wrapping it in a task would make the response instant and give you retries for free.
The existing S3 object still needs its ACL changed manually. The private storage fix applies to new uploads. Vicente_Reyes_Resume.pdf was already uploaded as public. Re-uploading via admin or changing the object ACL in the AWS console closes that gap.
