Emails

API reference for email sync operations

The emails module handles synchronization of Buttondown newsletter emails between remote API and local markdown files.

Overview

Emails are stored locally as markdown files with YAML frontmatter containing metadata. The module provides serialization, deserialization, and image reference resolution capabilities.

Types

Email

Based on the Buttondown API Email schema from OpenAPI specification.

FrontMatterFields

Metadata fields extracted to YAML frontmatter:

type FrontMatterFields = Pick<
  Email,
  | "id"
  | "subject"
  | "email_type"
  | "status"
  | "metadata"
  | "slug"
  | "publish_date"
  | "description"
  | "image"
  | "canonical_url"
  | "secondary_id"
  | "filters"
  | "commenting_mode"
  | "related_email_ids"
  | "featured"
>

RelativeImageReference

Represents a relative image path found in markdown content:

interface RelativeImageReference {
  match: string;          // Full markdown image syntax
  altText: string;        // Alt text from image
  relativePath: string;   // Relative path to image file
}

Serialization Functions

deserialize()

Parses markdown content with YAML frontmatter into an email object.

function deserialize(content: string): {
  email: Partial<Email>;
  isValid: boolean;
  error?: string;
}

content · string · required

Markdown content with YAML frontmatter delimited by ---

email · Partial<Email>

Parsed email object with frontmatter fields and body content

isValid · boolean

Whether the content was successfully parsed with valid frontmatter

error · string

Error message if parsing failed

Example

const result = deserialize(`---
id: abc123
subject: Welcome Newsletter
status: draft
---

Hello subscribers!`);

if (result.isValid) {
  console.log(result.email.subject); // "Welcome Newsletter"
  console.log(result.email.body);    // "Hello subscribers!"
}

serialize()

Converts an email object into markdown content with YAML frontmatter.

function serialize(email: Partial<Email & FrontMatterFields>): string

email · Partial<Email & FrontMatterFields> · required

Email object containing body and frontmatter fields

return · string

Formatted markdown with YAML frontmatter

Behavior

• Removes fields with null, undefined, empty string, or empty object/array values
• Excludes fields matching default values defined in FRONT_MATTER_FIELD_TO_DEFAULT_VALUE
• Strips editor mode sigils from body content
• Formats YAML with 2-space indentation

Example

const markdown = serialize({
  id: "abc123",
  subject: "Welcome Newsletter",
  status: "draft",
  body: "Hello subscribers!"
});

// Returns:
// ---
// id: abc123
// subject: Welcome Newsletter
// status: draft
// ---
//
// Hello subscribers!

Image Reference Functions

findRelativeImageReferences()

Finds all relative image references in markdown content.

function findRelativeImageReferences(
  content: string
): RelativeImageReference[]

content · string · required

Markdown content to search for image references

return · RelativeImageReference[]

Array of relative image references found (excludes absolute URLs)

Example

const refs = findRelativeImageReferences(
  "![Logo](./images/logo.png) ![Remote](https://example.com/img.png)"
);

// Returns only the relative reference:
// [{
//   match: "![Logo](./images/logo.png)",
//   altText: "Logo",
//   relativePath: "./images/logo.png"
// }]

replaceImageReference()

Replaces an image reference with a new URL.

function replaceImageReference(
  content: string,
  originalReference: string,
  newUrl: string,
  altText: string
): string

content · string · required

Markdown content containing the image reference

originalReference · string · required

Original markdown image syntax to replace

newUrl · string · required

New URL to use in the image reference

altText · string · required

Alt text for the image

return · string

Updated markdown content with replaced reference

resolveRelativeImageReferences()

Replaces relative image paths with absolute URLs from synced images.

function resolveRelativeImageReferences(
  content: string,
  emailDir: string,
  syncedImages: Record<string, { localPath: string; url: string }>
): string

content · string · required

Markdown content with relative image references

emailDir · string · required

Directory containing the email file (for resolving relative paths)

syncedImages · Record<string, SyncedImageInfo> · required

Map of synced images with local paths and remote URLs

return · string

Content with relative paths replaced by absolute URLs

convertAbsoluteToRelativeImages()

Converts absolute image URLs to relative paths for local storage.

function convertAbsoluteToRelativeImages(
  content: string,
  emailDir: string,
  syncedImages: Record<string, { localPath: string; url: string }>
): string

content · string · required

Markdown content with absolute image URLs

emailDir · string · required

Directory containing the email file

syncedImages · Record<string, SyncedImageInfo> · required

Map of synced images with local paths and remote URLs

return · string

Content with absolute URLs replaced by relative paths

Resource Objects

REMOTE_EMAILS_RESOURCE

Handles email operations with the Buttondown API.

const REMOTE_EMAILS_RESOURCE: Resource<Email[], Email[]>

Methods

get(configuration) - Fetches all emails from the API with pagination

set(value, configuration) - Creates or updates emails via API

• Adds markdown mode sigil to email body
• Updates emails with id, creates new emails without id
• Returns operation counts (created, updated, deleted, failed)

LOCAL_EMAILS_RESOURCE

Handles email operations with local markdown files.

const LOCAL_EMAILS_RESOURCE: Resource<Email[], string[]>

Methods

get(configuration) - Reads all .md files from emails/ directory

set(value, configuration) - Writes emails as markdown files

• Creates files at emails/{slug-or-id}.md
• Uses slug for filename if available, otherwise uses ID

EMAILS_RESOURCE

Combined resource group for email synchronization.

const EMAILS_RESOURCE: ResourceGroup<Email[], Email[], string[]>

Constants

FRONT_MATTER_FIELDS

Array of field names included in YAML frontmatter:

const FRONT_MATTER_FIELDS: (keyof FrontMatterFields)[] = [
  "id", "subject", "email_type", "status", "metadata",
  "slug", "publish_date", "description", "image",
  "canonical_url", "secondary_id", "filters",
  "commenting_mode", "related_email_ids", "featured"
]

FRONT_MATTER_FIELD_TO_DEFAULT_VALUE

Default values for fields (omitted from serialization if unchanged):

const FRONT_MATTER_FIELD_TO_DEFAULT_VALUE = {
  email_type: "public",
  featured: false,
  commenting_mode: "enabled",
  filters: { filters: [], groups: [], predicate: "and" },
  related_email_ids: []
}