Email Systems

Email has the highest ROI of any marketing channel. $36 for every $1 spent.

Yet most startups treat it as an afterthought - bulk blasts, no personalization,

landing in spam folders.

This skill covers transactional email that works, marketing automation that

converts, deliverability that reaches inboxes, and the infrastructure decisions

that scale.

Principles

• Transactional vs Marketing separation | Description: Transactional emails (password reset, receipts) need 100% delivery.

Marketing emails (newsletters, promos) have lower priority. Use separate

IP addresses and providers to protect transactional deliverability. | Examples: Good: Password resets via Postmark, marketing via ConvertKit | Bad: All emails through one SendGrid account

• Permission is everything | Description: Only email people who asked to hear from you. Double opt-in for marketing.

Easy unsubscribe. Clean your list ruthlessly. Bad lists destroy deliverability. | Examples: Good: Confirmed subscription + one-click unsubscribe | Bad: Scraped email list, hidden unsubscribe, bought contacts

• Deliverability is infrastructure | Description: SPF, DKIM, DMARC are not optional. Warm up new IPs. Monitor bounce rates.

Deliverability is earned through technical setup and good behavior. | Examples: Good: All DNS records configured, dedicated IP warmed for 4 weeks | Bad: Using free tier shared IP, no authentication records

• One email, one goal | Description: Each email should have exactly one purpose and one CTA. Multiple asks

means nothing gets clicked. Clear single action. | Examples: Good: "Click here to verify your email" (one button) | Bad: "Verify email, check out our blog, follow us on Twitter, refer a friend..."

• Timing and frequency matter | Description: Wrong time = low open rates. Too frequent = unsubscribes. Let users

set preferences. Test send times. Respect inbox fatigue. | Examples: Good: Weekly digest on Tuesday 10am user's timezone, preference center | Bad: Daily emails at random times, no way to reduce frequency

Patterns

Transactional Email Queue

Queue all transactional emails with retry logic and monitoring

When to use: Sending any critical email (password reset, receipts, confirmations)

// Don't block request on email send

await queue.add('email', {

template: 'password-reset',

to: user.email,

data: { resetToken, expiresAt }

}, {

attempts: 3,

backoff: { type: 'exponential', delay: 2000 }

});

Email Event Tracking

Track delivery, opens, clicks, bounces, and complaints

When to use: Any email campaign or transactional flow

Track lifecycle:

• Queued: Email entered system

• Sent: Handed to provider

• Delivered: Reached inbox

• Opened: Recipient viewed

• Clicked: Recipient engaged

• Bounced: Permanent failure

• Complained: Marked as spam

Template Versioning

Version email templates for rollback and A/B testing

When to use: Changing production email templates

templates/

password-reset/

v1.tsx (current)

v2.tsx (testing 10%)

v1-deprecated.tsx (archived)

Deploy new version gradually

Monitor metrics before full rollout

Bounce Handling State Machine

Automatically handle bounces to protect sender reputation

When to use: Processing bounce and complaint webhooks

switch (bounceType) {

case 'hard':

await markEmailInvalid(email);

break;

case 'soft':

await incrementBounceCount(email);

if (count >= 3) await markEmailInvalid(email);

break;

case 'complaint':

await unsubscribeImmediately(email);

break;

}

React Email Components

Build emails with reusable React components

When to use: Creating email templates

import { Button, Html } from '@react-email/components';

export default function WelcomeEmail({ userName }) {

return (

Welcome {userName}!

Get Started

);

}

Preference Center

Let users control email frequency and topics

When to use: Building marketing or notification systems

Preferences:

☑ Product updates (weekly)

☑ New features (monthly)

☐ Marketing promotions

☑ Account notifications (always)

Respect preferences in all sends

Required for GDPR compliance

Sharp Edges

Missing SPF, DKIM, or DMARC records

Severity: CRITICAL

Situation: Sending emails without authentication. Emails going to spam folder.

Low open rates. No idea why. Turns out DNS records were never set up.

Symptoms:

• Emails going to spam

• Low deliverability rates

• mail-tester.com score below 8

• No DMARC reports received

Why this breaks:

Email authentication (SPF, DKIM, DMARC) tells receiving servers you're

legit. Without them, you look like a spammer. Modern email providers

increasingly require all three.

Recommended fix:

Required DNS records:

SPF (Sender Policy Framework)

TXT record: v=spf1 include:_spf.google.com include:sendgrid.net ~all

DKIM (DomainKeys Identified Mail)

TXT record provided by your email provider

Adds cryptographic signature to emails

DMARC (Domain-based Message Authentication)

TXT record: v=DMARC1; p=quarantine; rua=mailto:dmarc@yourdomain.com

Verify setup:

• Send test email to mail-tester.com

• Check MXToolbox for record validation

• Monitor DMARC reports

Using shared IP for transactional email

Severity: HIGH

Situation: Password resets going to spam. Using free tier of email provider.

Some other customer on your shared IP got flagged for spam.

Your reputation is ruined by association.

Symptoms:

• Transactional emails in spam

• Inconsistent delivery

• Using same provider for marketing and transactional

Why this breaks:

Shared IPs share reputation. One bad actor affects everyone. For

critical transactional email, you need your own IP or a provider

with strict shared IP policies.

Recommended fix:

Transactional email strategy:

Option 1: Dedicated IP (high volume)

• Get dedicated IP from your provider

• Warm it up slowly (start with 100/day)

• Maintain consistent volume

Option 2: Transactional-only provider

• Postmark (very strict, great reputation)

• Includes shared pool with high standards

Separate concerns:

• Transactional: Postmark or Resend

• Marketing: ConvertKit or Customer.io

• Never mix marketing and transactional

Not processing bounce notifications

Severity: HIGH

Situation: Emailing same dead addresses over and over. Bounce rate climbing.

Email provider threatening to suspend account. List is 40% dead.

Symptoms:

• Bounce rate above 2%

• No webhook handlers for bounces

• Same emails failing repeatedly

Why this breaks:

Bounces damage sender reputation. Email providers track bounce rates.

Above 2% and you start looking like a spammer. Dead addresses must

be removed immediately.

Recommended fix:

Bounce handling requirements:

Hard bounces:

Remove immediately on first occurrence

Invalid address, domain doesn't exist

Soft bounces:

Retry 3 times over 72 hours

After 3 failures, treat as hard bounce

Implementation:

// Webhook handler for bounces

app.post('/webhooks/email', (req, res) => {

  const event = req.body;

  if (event.type === 'bounce') {

    await markEmailInvalid(event.email);

    await removeFromAllLists(event.email);

  }

});

Monitor:

Track bounce rate by campaign

Alert if bounce rate exceeds 1%

Missing or hidden unsubscribe link

Severity: CRITICAL

Situation: Users marking as spam because they cannot unsubscribe. Spam complaints

rising. CAN-SPAM violation. Email provider suspends account.

Symptoms:

• Hidden unsubscribe links

• Multi-step unsubscribe process

• No List-Unsubscribe header

• High spam complaint rate

Why this breaks:

Users who cannot unsubscribe will mark as spam. Spam complaints hurt

reputation more than unsubscribes. Also it is literally illegal.

CAN-SPAM, GDPR all require clear unsubscribe.

Recommended fix:

Unsubscribe requirements:

Visible:

• Above the fold in email footer

• Clear text, not hidden

• Not styled to be invisible

One-click:

• Link directly unsubscribes

• No login required

• No "are you sure" hoops

List-Unsubscribe header:

List-Unsubscribe: <mailto:unsubscribe@example.com>,

  <https://example.com/unsubscribe?token=xxx>

List-Unsubscribe-Post: List-Unsubscribe=One-Click

Preference center:

Option to reduce frequency instead of full unsubscribe

Sending HTML without plain text alternative

Severity: MEDIUM

Situation: Some users see blank emails. Spam filters flagging emails. Accessibility

issues for screen readers. Email clients that strip HTML show nothing.

Symptoms:

• No text/plain part in emails

• Blank emails for some users

• Lower engagement in some segments

Why this breaks:

Not everyone can render HTML. Screen readers work better with plain text.

Spam filters are suspicious of HTML-only. Multipart is the standard.

Recommended fix:

Always send multipart:

await resend.emails.send({

  from: 'you@example.com',

  to: 'user@example.com',

  subject: 'Welcome!',

  html: '<h1>Welcome!</h1><p>Thanks for signing up.</p>',

  text: 'Welcome!\n\nThanks for signing up.',

});

Auto-generate text from HTML:

Use html-to-text library as fallback

But hand-crafted plain text is better

Plain text should be readable:

Not just HTML stripped of tags

Actual formatted text content

Sending high volume from new IP immediately

Severity: HIGH

Situation: Just switched providers. Started sending 50,000 emails/day immediately.

Massive deliverability issues. New IP has no reputation. Looks like spam.

Symptoms:

• New IP/provider

• Sending high volume immediately

• Sudden deliverability drop

Why this breaks:

New IPs have no reputation. Sending high volume immediately looks

like a spammer who just spun up. You need to gradually build trust.

Recommended fix:

IP warm-up schedule:

Week 1: 50-100 emails/day

Week 2: 200-500 emails/day

Week 3: 500-1000 emails/day

Week 4: 1000-5000 emails/day

Continue doubling until at volume

Best practices:

• Start with most engaged users

• Send to Gmail/Microsoft first (they set reputation)

• Maintain consistent volume

• Don't spike and drop

During warm-up:

• Monitor deliverability closely

• Check feedback loops

• Adjust pace if issues arise

Emailing people who did not opt in

Severity: CRITICAL

Situation: Bought an email list. Scraped emails from LinkedIn. Added conference

contacts. Spam complaints through the roof. Provider suspends account.

Maybe a lawsuit.

Symptoms:

• Purchased email lists

• Scraped contacts

• High unsubscribe rate on first send

• Spam complaints above 0.1%

Why this breaks:

Permission-based email is not optional. It is the law (CAN-SPAM, GDPR).

It is also effective - unwilling recipients hurt your metrics and

reputation more than they help.

Recommended fix:

Permission requirements:

Explicit opt-in:

• User actively chooses to receive email

• Not pre-checked boxes

• Clear what they are signing up for

Double opt-in:

• Confirmation email with link

• Only add to list after confirmation

• Best practice for marketing lists

What you cannot do:

• Buy email lists

• Scrape emails from websites

• Add conference contacts without consent

• Use partner/customer lists without consent

Transactional exception:

Password resets, receipts, account alerts

do not need marketing opt-in

Emails that are mostly or entirely images

Severity: MEDIUM

Situation: Beautiful designed email that is one big image. Users with images

blocked see nothing. Spam filters flag it. Mobile loading is slow.

No one can copy text.

Symptoms:

• Single image emails

• No text content visible

• Missing or generic alt text

• Low engagement when images blocked

Why this breaks:

Images are blocked by default in many clients. Spam filters are

suspicious of image-only emails. Accessibility suffers. Load times

increase.

Recommended fix:

Balance images and text:

60/40 rule:

• At least 60% text content

• Images for enhancement, not content

Always include:

• Alt text on every image

• Key message in text, not just image

• Fallback for images-off view

Test:

• Preview with images disabled

• Should still be usable

Example:

<img

  src="hero.jpg"

  alt="Save 50% this week - use code SAVE50"

  style="max-width: 100%"

/>

<p>Use code <strong>SAVE50</strong> to save 50% this week.</p>

Missing or default preview text

Severity: MEDIUM

Situation: Inbox shows "View this email in browser" or random HTML as preview.

Lower open rates. First impression wasted on boilerplate.

Symptoms:

• View in browser as preview

• HTML code visible in preview

• No preview component in template

Why this breaks:

Preview text is prime real estate - appears right after subject line.

Default or missing preview text wastes this space. Good preview text

increases open rates 10-30%.

Recommended fix:

Add explicit preview text:

In HTML:

<div style="display:none;max-height:0;overflow:hidden;">

  Your preview text here. This appears in inbox preview.

  <!-- Add whitespace to push footer text out -->

  &#x26;nbsp;&#x26;zwnj;&#x26;nbsp;&#x26;zwnj;&#x26;nbsp;&#x26;zwnj;&#x26;nbsp;&#x26;zwnj;&#x26;nbsp;

</div>

With React Email:

<Preview>

  Your preview text here. This appears in inbox preview.

</Preview>

Best practices:

• Complement the subject line

• 40-100 characters optimal

• Create curiosity or value

• Different from first line of email

Not handling partial send failures

Severity: HIGH

Situation: Sending to 10,000 users. API fails at 3,000. No tracking of what sent.

Either double-send or lose 7,000. No way to know who got the email.

Symptoms:

• No per-recipient send logging

• Cannot tell who received email

• Double-sending issues

• No retry mechanism

Why this breaks:

Bulk sends fail partially. APIs timeout. Rate limits hit. Without

tracking individual send status, you cannot recover gracefully.

Recommended fix:

Track each send individually:

async function sendCampaign(emails: string[]) {

  const results = await Promise.allSettled(

    emails.map(async (email) => {

      try {

        const result = await resend.emails.send({ to: email, ... });

        await db.emailLog.create({

          email,

          status: 'sent',

          messageId: result.id,

        });

        return result;

      } catch (error) {

        await db.emailLog.create({

          email,

          status: 'failed',

          error: error.message,

        });

        throw error;

      }

    })

  );

  const failed = results.filter(r => r.status === 'rejected');

  // Retry failed sends or alert

}

Best practices:

• Log every send attempt

• Include message ID for tracking

• Build retry queue for failures

• Monitor success rate per campaign

Validation Checks

Missing plain text email part

Severity: WARNING

Emails should always include a plain text alternative

Message: Email being sent with HTML but no plain text part. Add 'text:' property for accessibility and deliverability.

Hardcoded from email address

Severity: WARNING

From addresses should come from environment variables

Message: From email appears hardcoded. Use environment variable for flexibility.

Missing bounce webhook handler

Severity: WARNING

Email bounces should be handled to maintain list hygiene

Message: Email provider used but no bounce handling detected. Implement webhook handler for bounces.

Missing List-Unsubscribe header

Severity: INFO

Marketing emails should include List-Unsubscribe header

Message: Marketing email detected without List-Unsubscribe header. Add header for better deliverability.

Synchronous email send in request handler

Severity: WARNING

Email sends should be queued, not blocking

Message: Email sent synchronously in request handler. Consider queuing for better reliability.

Email send without retry logic

Severity: INFO

Email sends should have retry mechanism for failures

Message: Email send without apparent retry logic. Add retry for transient failures.

Email API key in code

Severity: ERROR

API keys should come from environment variables

Message: Email API key appears hardcoded in source code. Use environment variable.

Bulk email without rate limiting

Severity: WARNING

Bulk sends should respect provider rate limits

Message: Bulk email sending without apparent rate limiting. Add throttling to avoid hitting limits.

Email without preview text

Severity: INFO

Emails should include preview/preheader text

Message: Email template without preview text. Add hidden preheader for inbox preview.

Email send without logging

Severity: WARNING

Email sends should be logged for debugging and auditing

Message: Email being sent without apparent logging. Log sends for debugging and compliance.

Collaboration

Delegation Triggers

• copy|subject|messaging|content -> copywriting (Email needs copy)

• design|template|visual|layout -> ui-design (Email needs design)

• track|analytics|measure|metrics -> analytics-architecture (Email needs tracking)

• infrastructure|deploy|server|queue -> devops (Email needs infrastructure)

Email Marketing Stack

Skills: email-systems, copywriting, marketing, analytics-architecture

Workflow:

1. Infrastructure setup (email-systems)

2. Template creation (email-systems)

3. Copy writing (copywriting)

4. Campaign launch (marketing)

5. Performance tracking (analytics-architecture)

Transactional Email

Skills: email-systems, backend, devops

Workflow:

1. Provider setup (email-systems)

2. Template coding (email-systems)

3. Queue integration (backend)

4. Monitoring (devops)

When to Use

Use this skill when the request clearly matches the capabilities and patterns described above.

Limitations

• Use this skill only when the task clearly matches the scope described above.

• Do not treat the output as a substitute for environment-specific validation, testing, or expert review.

• Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.