Background Jobs & Email

What are Background Jobs?

When a user clicks "Send Email" in your app, what should happen? If you send the email right there in the API handler, the user has to wait — maybe 2-5 seconds — while the email service processes the request. That's a terrible experience.

Instead, the smart approach is: the API handler puts a message on a queue saying"send this email", responds to the user immediately with "Email queued!", and a separate worker picks up that message and sends the email in the background. The user never waits.

Here are common tasks that should be background jobs instead of blocking the user's request:

• • Sending emails — welcome emails, password resets, order confirmations
• • Processing images — generating thumbnails, resizing uploads, optimizing file sizes
• • Generating reports — PDF exports, CSV downloads, analytics calculations
• • Cleanup tasks — removing orphaned files, purging expired sessions, archiving old data
• • Third-party API calls — payment webhooks, push notifications, syncing with external services

How asynq Works

Grit uses asynq — a Go library for distributed task processing backed by Redis. It's simple, fast, and battle-tested. Here's how the pieces fit together:

The flow works in 4 steps:

1. 1.Handler dispatches a task — Your API handler creates a task with a type and payload, then pushes it to Redis via the asynq client.
2. 2.Worker picks it up — The asynq worker process polls Redis, sees the new task, and dequeues it.
3. 3.Worker processes it — The worker matches the task type to a registered handler function and executes it.
4. 4.Task marked done/failed — If the handler returns nil, the task is marked as completed. If it returns an error, it's marked as failed and may be retried.

┌──────────────┐     enqueue     ┌─────────┐     dequeue     ┌──────────────┐
│  API Handler  │ ──────────────► │  Redis  │ ◄────────────── │    Worker    │
│  (producer)   │                 │ (broker) │                 │  (consumer)  │
└──────────────┘                 └─────────┘                 └──────────────┘
                                                                    │
                                                                    ▼
                                                            ┌──────────────┐
                                                            │  Task Handler │
                                                            │  (your code)  │
                                                            └──────────────┘

docker compose ps

Built-in Workers

Grit comes with 3 workers out of the box. You don't need to build them — they're already wired up and ready to process tasks the moment your app starts.

• Email worker — Sends transactional emails via Resend. Handles welcome emails, password resets, email verification, and custom notifications. If Resend is down, the task retries automatically.
• Image worker — Generates thumbnails after a file is uploaded. Resizes images to multiple dimensions, optimizes file size, and stores the results back in S3/MinIO.
• Cleanup worker — Removes old or orphaned files. Runs on a schedule to purge expired uploads, temporary files, and data that's no longer referenced by any record.

All worker code lives in a single directory:

apps/api/internal/jobs/
├── email.go        # Email worker — sends emails via Resend
├── image.go        # Image worker — generates thumbnails
├── cleanup.go      # Cleanup worker — removes orphaned files
├── scheduler.go    # Cron scheduler — recurring tasks
└── worker.go       # Worker setup — registers all handlers

Creating a Custom Job

Let's walk through creating a custom background job step by step. We'll build a report generation job — when a user requests a report, we'll queue it and generate it in the background.

Every asynq job has 4 parts: a task type (a string identifier), a payload (data the worker needs), a handler (the function that does the work), and a registration (telling the worker about the handler).

Step 1: Define the Task Type and Payload

The task type is a unique string that identifies this kind of job. The payload is a struct containing all the data the worker needs to process the task.

package jobs

const TypeReportGenerate = "report:generate"

type ReportPayload struct {
    UserID uint   `json:"user_id"`
    Type   string `json:"type"`
}

Step 2: Create the Handler

The handler is a function that receives the task, unmarshals the payload, and does the actual work. If it returns nil, the task is marked as completed. If it returns an error, the task is marked as failed and may be retried.

func HandleReportGenerate(ctx context.Context, t *asynq.Task) error {
    var p ReportPayload
    if err := json.Unmarshal(t.Payload(), &p); err != nil {
        return err
    }

    // Generate the report...
    log.Printf("Generating %s report for user %d", p.Type, p.UserID)

    // In a real app, you would:
    // 1. Query the database for the relevant data
    // 2. Format it into a PDF or CSV
    // 3. Upload the file to S3
    // 4. Notify the user that the report is ready

    return nil
}

Step 3: Register the Handler

In worker.go, register the handler so the worker knows which function to call when it sees a task with this type:

mux.HandleFunc(TypeReportGenerate, HandleReportGenerate)

Step 4: Dispatch from a Handler or Service

Finally, enqueue the task from your API handler or service. Create the payload, wrap it in an asynq task, and enqueue it:

payload, _ := json.Marshal(jobs.ReportPayload{
    UserID: 1,
    Type:   "monthly",
})
task := asynq.NewTask(jobs.TypeReportGenerate, payload)
info, err := client.Enqueue(task)
if err != nil {
    // Handle error
}
log.Printf("Task enqueued: id=%s queue=%s", info.ID, info.Queue)

Retry Logic

What happens when a background job fails? Maybe the email API is down, or the database is temporarily unavailable. You don't want to lose the task — you want to retry it.

asynq handles this automatically. By default, failed tasks are retried 3 times with exponential backoff. Each retry waits longer than the last, giving the failing service time to recover.

You can configure retry behavior per task when you enqueue it:

// Retry up to 5 times (default is 3)
client.Enqueue(task, asynq.MaxRetry(5))

// Delay processing by 10 seconds
client.Enqueue(task, asynq.ProcessIn(10 * time.Second))

// Set a deadline — fail if not completed by this time
client.Enqueue(task, asynq.Deadline(time.Now().Add(1 * time.Hour)))

// Combine options
client.Enqueue(task,
    asynq.MaxRetry(5),
    asynq.ProcessIn(30 * time.Second),
    asynq.Queue("critical"),
)

Cron Scheduler

Some tasks need to run on a schedule — not triggered by a user action, but by the clock. Clean up expired sessions every night. Generate a daily report at 9am. Check for abandoned carts every hour. These are scheduled tasks.

Grit uses asynq's built-in scheduler. Here's the cron expression format:

┌───────── minute (0-59)
│ ┌─────── hour (0-23)
│ │ ┌───── day of month (1-31)
│ │ │ ┌─── month (1-12)
│ │ │ │ ┌─ day of week (0-6, 0=Sunday)
│ │ │ │ │
* * * * *

The * means "every". Here are common patterns:

Here's how Grit registers scheduled tasks in the scheduler:

scheduler := asynq.NewScheduler(redisOpt, nil)

// Clean up orphaned files every day at 2am
scheduler.Register("0 2 * * *", asynq.NewTask(TypeCleanupFiles, nil))

// Generate daily stats at midnight
scheduler.Register("0 0 * * *", asynq.NewTask(TypeStatsDaily, nil))

// Check for expired sessions every hour
scheduler.Register("0 * * * *", asynq.NewTask(TypeSessionCleanup, nil))

Admin Jobs Dashboard

Grit's admin panel includes a built-in Jobs dashboard where you can monitor all background tasks. No need for a separate monitoring tool — it's right there in your admin panel.

The Jobs page shows tasks grouped by status:

• • Active — tasks currently being processed by a worker
• • Pending — tasks waiting in the queue to be picked up
• • Completed — tasks that finished successfully
• • Failed — tasks that failed after all retries were exhausted
• • Scheduled — tasks delayed with ProcessIn, waiting for their time

For each failed task, you can see the error message, how many times it was retried, and when it last failed. You can also retry a failed task directly from the dashboard — no code changes needed.

What is Transactional Email?

There are two kinds of email in web applications: marketing email and transactional email. They serve very different purposes.

Here's how they differ:

Grit uses Resend for transactional email. Resend is a modern email API designed for developers — simple, reliable, and with excellent deliverability. In local development, Grit uses Mailhog to catch all outgoing emails so you can preview them without sending real emails.

Email Configuration

Email configuration lives in your .env file. There are two variables you need:

# Email — Resend
RESEND_API_KEY=re_xxxxxxxxxxxxxxxxxxxx
MAIL_FROM=noreply@yourapp.com

RESEND_API_KEY is your API key from resend.com.MAIL_FROM is the "from" address that appears on all outgoing emails.

For local development, you don't need a real Resend API key. Grit's Docker Compose includes Mailhog — a fake SMTP server that catches all outgoing emails and displays them in a web UI at localhost:8025.

mailhog:
  image: mailhog/mailhog
  ports:
    - "1025:1025"   # SMTP port — your app sends here
    - "8025:8025"   # Web UI — view caught emails here

Email Templates

Grit includes 4 pre-built HTML email templates that cover the most common transactional email needs. They're clean, responsive, and ready to customize.

• • welcome — sent when a user registers a new account
• • password-reset — sent when a user requests a password reset link
• • verify-email — sent to confirm a user's email address
• • notification — a generic template for custom notifications

All templates live in the apps/api/internal/mail/ directory:

apps/api/internal/mail/
├── mailer.go             # Send function, SMTP config
├── templates/
│   ├── welcome.html      # Welcome email template
│   ├── password-reset.html
│   ├── verify-email.html
│   └── notification.html

Templates use Go's built-in html/template package. Dynamic data is injected using double curly braces:

<!DOCTYPE html>
<html>
<head>
    <style>
        body { font-family: sans-serif; background: #f4f4f4; padding: 20px; }
        .container { max-width: 600px; margin: 0 auto; background: #fff; padding: 32px; border-radius: 8px; }
        .button { background: #6c5ce7; color: #fff; padding: 12px 24px; text-decoration: none; border-radius: 6px; }
    </style>
</head>
<body>
    <div class="container">
        <h1>Welcome, {{.Name}}!</h1>
        <p>Thanks for joining {{.AppName}}. We're excited to have you.</p>
        <p><a href="{{.DashboardURL}}" class="button">Go to Dashboard</a></p>
    </div>
</body>
</html>

The {{.Name}} syntax is Go's template language. When you send the email, you pass a map of data, and Go replaces each {{.Key}} with the corresponding value.

Sending Email from Code

Sending an email from your Go code is straightforward. Grit provides a mailer package with a Send function that handles template rendering and delivery.

err := mailer.Send(mail.Email{
    To:       "user@example.com",
    Subject:  "Welcome!",
    Template: "welcome",
    Data: map[string]string{
        "Name":         "John",
        "AppName":      "My App",
        "DashboardURL": "https://myapp.com/dashboard",
    },
})

The Template field matches one of the HTML files in the templates/ directory (without the .html extension). The Data map provides the values for all the {{.Key}} placeholders in the template.

But remember — you should never send emails directly from an API handler. Instead, dispatch a background job that sends the email. This way the user's request isn't blocked by the email service:

// In your handler or service
payload, _ := json.Marshal(jobs.EmailPayload{
    To:       "user@example.com",
    Subject:  "Welcome!",
    Template: "welcome",
    Data:     map[string]string{"Name": "John"},
})
task := asynq.NewTask(jobs.TypeEmailSend, payload)
client.Enqueue(task)

// The email worker will pick this up and call mailer.Send()

Summary

In this course, you learned how to offload slow or unreliable tasks to background workers using asynq and Redis, and how to send transactional emails with Go templates and Resend. Here's what you covered:

• Background jobs — tasks that run asynchronously outside the user's request, keeping the API fast
• asynq architecture — producers enqueue tasks to Redis, workers dequeue and process them
• Built-in workers — email, image processing, and cleanup workers come pre-configured
• Custom jobs — 4 steps: define task type, create handler, register it, dispatch from your code
• Retry logic — exponential backoff with configurable max retries and delayed processing
• Cron scheduler — recurring tasks on a schedule using cron expressions
• Admin Jobs dashboard — monitor active, pending, completed, and failed tasks from the admin panel
• Transactional email — user-triggered emails using Resend, with Go HTML templates and Mailhog for local dev