finsilabs/email-service-integration

Email Service Integration

Overview

Transactional emails — order confirmations, shipping notifications, password resets, and account alerts — are critical customer touchpoints that must arrive instantly and reliably. This skill covers setting up email delivery on each platform and integrating dedicated transactional services (SendGrid, Amazon SES, Postmark) with SPF/DKIM/DMARC DNS records for deliverability, reusable templates, and bounce/complaint handling.

When to Use This Skill

• When setting up transactional email for a new e-commerce store
• When emails are landing in spam due to missing SPF, DKIM, or DMARC records
• When migrating from a platform's built-in email to a dedicated transactional service
• When building custom email templates that match your brand identity
• When tracking email delivery, open rates, and bounces for transactional emails

Core Instructions

Step 1: Determine your platform and recommended approach

| Platform | Default Email | Recommended Upgrade | |----------|--------------|-------------------| | Shopify | Shopify Email (built-in, branded templates, free up to 10K/month) | Customize templates in Settings → Notifications; for high volume or advanced flows use Klaviyo or Omnisend | | WooCommerce | WordPress sends via your hosting server (poor deliverability) | Install FluentSMTP (free) to route via SendGrid/SES/Postmark; use WooCommerce Email Customizer ($49) for branded templates | | BigCommerce | BigCommerce built-in transactional email (basic templates) | Customize templates in Marketing → Transactional Emails; for advanced templates use Klaviyo BigCommerce integration | | Custom / Headless | None — you build it | Integrate SendGrid, Postmark, or Amazon SES directly; build templates with React Email; see implementation below |

Step 2: Platform-specific email setup

---

Shopify

Customize built-in transactional emails:

1. Go to Settings → Notifications in your Shopify admin
2. Click any notification type (Order Confirmation, Shipping Notification, etc.) to open the editor
3. Edit the HTML/Liquid template directly — Shopify provides liquid variables for order data
4. Upload your logo in Online Store → Themes → Customize → Theme settings → Logo — it appears automatically in notification emails
5. In Settings → General, set your sender email — Shopify authenticates it automatically via SPF/DKIM

Set up Shopify Email for marketing flows:

1. Go to Apps → Shopify Email (free, included with all plans up to 10,000 emails/month)
2. Build order confirmation, shipping, and post-purchase flows with the drag-and-drop editor
3. For advanced automations (abandoned cart sequences, win-back flows) upgrade to Klaviyo (free up to 500 contacts) which has a pre-built Shopify integration

---

WooCommerce

Fix email deliverability with FluentSMTP:

1. Install FluentSMTP (free, wordpress.org) — this replaces WordPress's built-in PHP mail with a dedicated SMTP or API provider
2. Go to FluentSMTP → Settings → Add New Connection
3. Choose your provider: SendGrid (free tier: 100 emails/day), Mailgun (free tier: 1,000 emails/month), or Amazon SES ($0.10/1,000 emails)
4. Enter your API key and set From Name and From Email to match your domain
5. Send a test email from FluentSMTP to verify delivery

Set up SPF and DKIM for your sending domain:

Most providers give you specific DNS records to add. For SendGrid:

• Add the two CNAME records SendGrid provides to your DNS (usually in your domain registrar or Cloudflare)
• In SendGrid, verify the domain — this takes up to 48 hours to propagate
• After verification, emails show "via yourdomain.com" in Gmail, not "via sendgrid.net"

Customize WooCommerce email templates:

1. Install Email Customizer for WooCommerce by ThemeHigh (free tier; Pro from $49)
2. Go to WooCommerce → Email Customizer to drag-and-drop your logo, colors, and footer into each email type
3. Or install Kadence WooCommerce Email Designer (free) for a live preview editor

---

BigCommerce

Customize transactional email templates:

1. Go to Marketing → Transactional Emails in your BigCommerce admin
2. Click any email type (Order Confirmation, Shipment Notification, etc.) and click Edit Template
3. Edit the HTML template using BigCommerce's template variables (e.g., %%ORDER_NUMBER%%, %%TOTAL_COST%%)
4. In Store Setup → Store Profile, set your sending name and reply-to address

Connect Klaviyo for advanced flows:

1. Install the Klaviyo app from the BigCommerce App Marketplace (free to install)
2. Klaviyo syncs your BigCommerce order and customer data automatically
3. Use Klaviyo's pre-built BigCommerce flows for order confirmation, shipping, and abandoned cart emails

---

Custom / Headless

Configure DNS for deliverability first — SPF, DKIM, and DMARC are mandatory before any emails reach inboxes:

; SPF — authorize SendGrid to send on behalf of your domain
mystore.com.  IN TXT  "v=spf1 include:sendgrid.net ~all"

; DKIM — SendGrid provides two CNAME records:
s1._domainkey.mystore.com  IN CNAME  s1.domainkey.u12345.wl.sendgrid.net.
s2._domainkey.mystore.com  IN CNAME  s2.domainkey.u12345.wl.sendgrid.net.

; DMARC — start with p=none to monitor, then escalate to p=quarantine
_dmarc.mystore.com  IN TXT  "v=DMARC1; p=none; rua=mailto:[email protected]"

Verify with mxtoolbox.com/SuperTool.aspx before sending.

SendGrid API integration:

// lib/email/sendgrid.ts
import sgMail from '@sendgrid/mail';
sgMail.setApiKey(process.env.SENDGRID_API_KEY!);

export async function sendEmail(params: {
  to: string;
  subject: string;
  html: string;
  text: string;
}) {
  await sgMail.send({
    to: params.to,
    from: { email: '[email protected]', name: 'My Store' },
    subject: params.subject,
    html: params.html,
    text: params.text,
    trackingSettings: {
      clickTracking: { enable: false },  // Don't wrap links in transactional emails
      openTracking: { enable: true },
    },
  });
}

Build templates with React Email (npm install @react-email/components):

// emails/order-confirmation.tsx
import { Body, Container, Heading, Html, Img, Preview, Section, Text, Row, Column } from '@react-email/components';

export function OrderConfirmationEmail({ orderNumber, customerName, items, total, trackingUrl }) {
  return (
    <Html>
      <Preview>Your order #{orderNumber} is confirmed</Preview>
      <Body style={{ backgroundColor: '#f4f4f4', fontFamily: 'Arial, sans-serif' }}>
        <Container style={{ maxWidth: '600px', margin: '0 auto', backgroundColor: '#fff', padding: '20px' }}>
          <Heading>Order Confirmed</Heading>
          <Text>Hi {customerName}, your order #{orderNumber} has been received.</Text>
          {items.map((item, i) => (
            <Row key={i} style={{ borderBottom: '1px solid #eee', padding: '10px 0' }}>
              <Column style={{ width: '60px' }}>
                <Img src={item.imageUrl} width={50} height={50} alt={item.name} />
              </Column>
              <Column>
                <Text style={{ margin: 0, fontWeight: 'bold' }}>{item.name}</Text>
                <Text style={{ margin: 0, color: '#666' }}>Qty: {item.quantity}</Text>
              </Column>
              <Column style={{ textAlign: 'right' }}>
                <Text style={{ margin: 0 }}>{item.price}</Text>
              </Column>
            </Row>
          ))}
          <Section style={{ marginTop: '20px' }}>
            <Text style={{ fontWeight: 'bold', fontSize: '18px' }}>Total: {total}</Text>
          </Section>
        </Container>
      </Body>
    </Html>
  );
}

Render and send:

import { render } from '@react-email/render';
import { OrderConfirmationEmail } from '../../emails/order-confirmation';
import { sendEmail } from './sendgrid';

export async function sendOrderConfirmation(order: Order) {
  const html = await render(OrderConfirmationEmail({ ...orderData }));
  const text = await render(OrderConfirmationEmail({ ...orderData }), { plainText: true });

  await sendEmail({
    to: order.customer.email,
    subject: `Your order #${order.number} is confirmed`,
    html,
    text,
  });
}

Handle bounces and complaints via webhook:

// POST /api/webhooks/sendgrid
export async function POST(req: NextRequest) {
  const events = await req.json();
  for (const event of events) {
    if (event.event === 'bounce') {
      await db.emailSuppressions.upsert({ email: event.email, type: 'hard_bounce' });
    }
    if (event.event === 'spamreport') {
      await db.emailSuppressions.upsert({ email: event.email, type: 'spam_complaint' });
    }
  }
  return NextResponse.json({ received: true });
}

// Check suppression list before every send
export async function canSendEmail(email: string): Promise<boolean> {
  const suppression = await db.emailSuppressions.findByEmail(email.toLowerCase());
  return !suppression; // Never send to hard bounced or spam-complaint addresses
}

Best Practices

• Use separate sending domains for transactional and marketing emails — bounces and spam complaints from marketing campaigns should not affect your transactional domain reputation
• Always include a plain-text version — missing plain text can trigger spam filters; React Email renders it automatically with { plainText: true }
• Suppress hard bounced addresses immediately — sending to non-existent addresses harms your sender reputation; store and check suppressions before every send
• Never track clicks in transactional emails — link tracking wraps URLs in redirects, which can look suspicious in password reset and order confirmation emails
• Test rendering across email clients — Outlook, Gmail, and Apple Mail render HTML very differently; use Litmus or Email on Acid to validate before deploying templates

Common Pitfalls

| Problem | Solution | |---------|----------| | WooCommerce emails going to spam | Install FluentSMTP to send via SendGrid or SES; WordPress's default PHP mail has no SPF/DKIM and almost always gets marked as spam | | SES sandbox blocking delivery | New AWS accounts start in SES sandbox mode — request production access via AWS Support before going live | | Duplicate order confirmation emails | Implement idempotent sending: emailId = hash(orderId + 'order-confirmation') and check before sending | | Emails landing in spam despite SPF/DKIM | Check DMARC alignment; your From: domain must match the domain in the DKIM d= tag | | React Email CSS broken in Outlook | Use inline styles for everything; Outlook ignores <style> blocks; @react-email/components handles this for built-in components |

Related Skills

• @gdpr-ecommerce
• @webhook-architecture
• @analytics-integration