Emails

Send transactional and marketing emails with automatic PII protection.

Send an Email

Send a single email to one or more recipients.

POST /v1/emails

Request Body

Parameter	Type	Description
from	string	Sender email address (required)
to	string \| string[]	Recipient email address(es) (required)
subject	string	Email subject line (required)
html	string	HTML body content
text	string	Plain text body content
cc	string \| string[]	CC recipients
bcc	string \| string[]	BCC recipients
replyTo	string	Reply-to address
templateId	string	Template ID to use
variables	object	Variables for template rendering
scheduledAt	string	ISO 8601 datetime for scheduled delivery
tags	string[]	Tags for categorization
metadata	object	Custom key-value metadata

Example

send-email.ts

const email = await client.emails.send({
  from: 'hello@yourdomain.com',
  to: 'user@example.com',
  subject: 'Welcome to our platform!',
  html: `
    <h1>Welcome, {{name}}!</h1>
    <p>Thanks for signing up.</p>
  `,
  variables: {
    name: 'John',
  },
  tags: ['welcome', 'onboarding'],
});

Send with Template

Use a pre-defined template instead of providing HTML inline.

send-with-template.ts

const email = await client.emails.send({
  from: 'hello@yourdomain.com',
  to: 'user@example.com',
  templateId: 'template_xxxxx',
  variables: {
    firstName: 'John',
    orderNumber: '12345',
    items: [
      { name: 'Widget', price: 29.99 },
      { name: 'Gadget', price: 49.99 },
    ],
  },
});

Schedule Email

Schedule an email to be sent at a specific time.

schedule-email.ts

const email = await client.emails.send({
  from: 'hello@yourdomain.com',
  to: 'user@example.com',
  subject: 'Your weekly digest',
  html: '<h1>Weekly Digest</h1>',
  scheduledAt: '2024-12-25T09:00:00Z',
});

// Cancel a scheduled email
await client.emails.cancel(email.id);

List Emails

Retrieve a list of emails with optional filters.

GET /v1/emails

list-emails.ts

// List all emails
const { data, hasMore, nextCursor } = await client.emails.list();

// Filter by status
const delivered = await client.emails.list({
  status: 'delivered',
  limit: 50,
});

// Paginate through results
let cursor;
do {
  const page = await client.emails.list({ cursor, limit: 100 });
  console.log(page.data);
  cursor = page.nextCursor;
} while (cursor);

Get Email

Retrieve a single email by ID.

GET /v1/emails/:id

get-email.ts

const email = await client.emails.get('email_xxxxx');

console.log(email.status);     // 'delivered'
console.log(email.sentAt);     // '2024-01-01T12:00:00Z'
console.log(email.piiDetected); // false

Email Status

Emails progress through the following statuses:

Status	Description
`pending`	Email is being processed
`queued`	Email is queued for sending
`sending`	Email is being sent
`sent`	Email was sent successfully
`delivered`	Email was delivered to recipient
`bounced`	Email bounced (hard or soft)
`failed`	Email failed to send
`cancelled`	Scheduled email was cancelled

PII Detection

Emails are automatically scanned for PII before sending. The behavior depends on your account settings:

PII Blocking Mode

When enabled, emails containing PII will be blocked and return a 422 error with details about the detected PII types.

pii-detection.ts

import { PiiDetectedError } from '@veilmail/sdk';

try {
  await client.emails.send({
    from: 'hello@yourdomain.com',
    to: 'user@example.com',
    subject: 'Your order',
    html: 'Your SSN is 123-45-6789', // Contains PII!
  });
} catch (error) {
  if (error instanceof PiiDetectedError) {
    console.log('PII detected:', error.piiTypes);
    // ['US_SOCIAL_SECURITY_NUMBER']
  }
}