Migrate from SendGrid

Overview

Veil Mail offers a modern, privacy-first alternative to SendGrid with built-in PII protection, CASL compliance tools, and a developer experience designed for today's applications. If you're currently using SendGrid, migrating to Veil Mail is straightforward because both platforms share similar REST API conventions and Handlebars-based templating.

Key differences to be aware of:

• Veil Mail scans all outgoing emails for PII before delivery, preventing accidental data leaks
• API keys in Veil Mail are scoped to specific permissions and environments (veil_live_ for production, veil_test_ for testing)
• Audiences and subscribers are first-class resources with built-in consent tracking
• Webhook events use a namespaced format (e.g., email.delivered instead of delivered)

API Key Migration

SendGrid uses a single API key format. Veil Mail uses scoped API keys that separate production and test environments. Generate a new API key from the Veil Mail dashboard and replace your SendGrid key.

SendGrid

// SendGrid API key
SENDGRID_API_KEY=SG.xxxxxxxxxxxxxxxxxxxxx

Veil Mail

// Veil Mail API key (scoped to environment)
VEILMAIL_API_KEY=veil_live_xxxxx   # Production
# VEILMAIL_API_KEY=veil_test_xxxxx # Testing (no emails sent)

SDK Migration

Replace the @sendgrid/mail package with @resonia/veilmail-sdk. The API surface is intentionally similar to make migration easy.

# Remove SendGrid
npm uninstall @sendgrid/mail @sendgrid/client

# Install Veil Mail
npm install @resonia/veilmail-sdk

Send Email Comparison

SendGrid

import sgMail from '@sendgrid/mail';

sgMail.setApiKey(process.env.SENDGRID_API_KEY!);

await sgMail.send({
  to: 'user@example.com',
  from: 'hello@yourdomain.com',
  subject: 'Welcome!',
  html: '<h1>Welcome to our platform!</h1>',
});

Veil Mail

import { VeilMail } from '@resonia/veilmail-sdk';

const client = new VeilMail('veil_live_xxxxx');

await client.emails.send({
  to: 'user@example.com',
  from: 'hello@yourdomain.com',
  subject: 'Welcome!',
  html: '<h1>Welcome to our platform!</h1>',
});

Template Usage Comparison

SendGrid

await sgMail.send({
  to: 'user@example.com',
  from: 'hello@yourdomain.com',
  templateId: 'd-xxxxxxxxxxxxx',
  dynamicTemplateData: {
    firstName: 'Alice',
    orderNumber: '12345',
  },
});

Veil Mail

await client.emails.send({
  to: 'user@example.com',
  from: 'hello@yourdomain.com',
  templateId: 'template_xxxxx',
  templateData: {
    firstName: 'Alice',
    orderNumber: '12345',
  },
});

API Endpoint Mapping

The following table maps common SendGrid API endpoints to their Veil Mail equivalents.

Webhook Migration

SendGrid uses flat event names in its Event Webhook. Veil Mail uses namespaced event types. Update your webhook handler to map the new event names.

Veil Mail webhooks also include a signature header (X-VeilMail-Signature) for verification, similar to SendGrid's Event Webhook signature verification.

// Veil Mail webhook handler
app.post('/webhooks/veilmail', async (req, res) => {
  const signature = req.headers['x-veilmail-signature'];
  // Verify signature with your webhook secret

  const event = req.body;

  switch (event.type) {
    case 'email.delivered':
      // Previously: event === 'delivered'
      break;
    case 'email.bounced':
      // Previously: event === 'bounce'
      break;
    case 'email.complained':
      // Previously: event === 'spamreport'
      break;
  }

  res.json({ received: true });
});

Template Migration

Both SendGrid and Veil Mail use Handlebars syntax for templates, so your existing template content is largely compatible. The main differences are in how templates are managed and referenced.

Compatible Syntax

• Variable substitution: {{variableName}}
• Conditionals: {{#if condition}}...{{/if}}
• Loops: {{#each items}}...{{/each}}
• Helpers: {{formatDate date}}

What to Update

• Replace dynamicTemplateData with templateData in your send calls
• Update template IDs from d-xxxxx format to template_xxxxx format
• Recreate templates in the Veil Mail dashboard or via the API

What's Different

What You Gain

• Automatic PII protection -- every email is scanned for sensitive data before delivery, preventing accidental data leaks
• Built-in CASL compliance -- consent tracking, unsubscribe management, and physical address enforcement out of the box
• Environment-scoped API keys -- test safely with veil_test_ keys that never send real emails
• A/B testing and automation -- built-in campaign A/B testing, drip sequences, and automation workflows
• SDKs for every language -- official SDKs for Node.js, Python, Go, Ruby, PHP, Java, .NET, Rust, Elixir, and more
• RSS-to-email and signup forms -- automated content delivery and embeddable subscriber forms