DEV Community

Cover image for Building a Resume Download Gate: Email Collection, Signed Tokens, and an S3 Lesson
Vicente G. Reyes
Vicente G. Reyes

Posted on • Originally published at vicentereyes.org

Building a Resume Download Gate: Email Collection, Signed Tokens, and an S3 Lesson

#django #python #webdev #tutorial

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:

  1. Visitor clicks "Download Resume" on the About page or Hero
  2. A modal asks for their email
  3. Backend validates the email (format + disposable domain check)
  4. A signed, time-limited link is emailed to them
  5. 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)
Enter fullscreen mode Exit fullscreen mode

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"]
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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"}
Enter fullscreen mode Exit fullscreen mode

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,
            )
Enter fullscreen mode Exit fullscreen mode 
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)
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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()
Enter fullscreen mode Exit fullscreen mode 
# models.py
class Resume(models.Model):
    pdf = models.FileField(upload_to="resume/", storage=private_resume_storage)
Enter fullscreen mode Exit fullscreen mode

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=...
Enter fullscreen mode Exit fullscreen mode

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...", ...})
Enter fullscreen mode Exit fullscreen mode

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
)}
Enter fullscreen mode Exit fullscreen mode

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>",
)
Enter fullscreen mode Exit fullscreen mode

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│
Enter fullscreen mode Exit fullscreen mode

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.

Top comments (0)