Automations

API reference for automation sync operations

The automations module handles synchronization of Buttondown automations between the API and local JSON files.

Overview

Automations are stored locally as JSON files in the automations/ directory. Each automation defines triggers, actions, and filters for automated newsletter workflows.

Types

Automation

Based on the Buttondown API Automation schema from OpenAPI specification.

type Automation = components["schemas"]["Automation"]

SerializedAutomation

Subset of automation fields included in local JSON files:

type SerializedAutomation = Pick<
  Automation,
  | "id"
  | "name"
  | "status"
  | "trigger"
  | "actions"
  | "filters"
  | "metadata"
  | "should_evaluate_filter_after_delay"
>

Fields

id · string

Unique identifier for the automation

name · string · required

Human-readable name for the automation

status · string

Current status (e.g., “active”, “paused”)

trigger · object

Event that triggers the automation

actions · array

Array of actions to execute when triggered

filters · object

Subscriber filters to limit automation scope

metadata · object

Custom metadata key-value pairs

should_evaluate_filter_after_delay · boolean

Whether to re-evaluate filters after delay

Serialization Functions

serialize()

Converts an automation object to JSON string.

function serialize(automation: Partial<Automation>): string

automation · Partial<Automation> · required

Automation object to serialize

return · string

Formatted JSON string with 2-space indentation

Behavior

• Only includes fields defined in SERIALIZED_FIELDS
• Excludes fields with null or undefined values
• Formats JSON with 2-space indentation for readability

Example

const automation = {
  id: "auto_123",
  name: "Welcome Series",
  status: "active",
  trigger: { type: "subscriber_created" },
  actions: [{ type: "send_email", email_id: "email_456" }]
};

const json = serialize(automation);
console.log(json);
// {
//   "id": "auto_123",
//   "name": "Welcome Series",
//   "status": "active",
//   "trigger": { "type": "subscriber_created" },
//   "actions": [{ "type": "send_email", "email_id": "email_456" }]
// }

deserialize()

Parses JSON string into an automation object.

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

content · string · required

JSON string to parse

automation · Partial<Automation>

Parsed automation object

isValid · boolean

Whether the content was successfully parsed with required fields

error · string

Error message if parsing failed or validation error

Validation

• Must be valid JSON
• Must include name field (returns isValid: false if missing)
• Only extracts fields defined in SERIALIZED_FIELDS

Example

const json = `{
  "name": "Welcome Series",
  "status": "active"
}`;

const result = deserialize(json);

if (result.isValid) {
  console.log(result.automation.name); // "Welcome Series"
} else {
  console.error(result.error);
}

Utility Functions

slugify()

Converts automation name to filename-safe slug.

function slugify(name: string): string

name · string · required

Automation name to convert

return · string

Lowercase slug with hyphens

Example

slugify("Welcome Series")           // "welcome-series"
slugify("Post-Purchase Follow-up")  // "post-purchase-follow-up"
slugify("Re-Engagement Campaign!")   // "re-engagement-campaign"

Resource Objects

REMOTE_AUTOMATIONS_RESOURCE

Handles automation operations with the Buttondown API.

const REMOTE_AUTOMATIONS_RESOURCE: Resource<Automation[], Automation[]>

Methods

get(configuration)

Fetches all automations from the API with pagination.

async get(configuration: Configuration): Promise<Automation[]>

configuration · Configuration · required

Configuration with API credentials

return · Automation[]

Array of all automations

• Automatically handles pagination (100 items per page)
• Continues until all automations are retrieved

set(value, configuration)

Creates or updates automations via the API.

async set(
  value: Automation[],
  configuration: Configuration
): Promise<OperationResult>

value · Automation[] · required

Array of automations to create or update

configuration · Configuration · required

Configuration with API credentials

return · OperationResult

Counts of created, updated, deleted, and failed operations

Behavior

• Updates automations that have an id field (PATCH)
• Creates new automations without an id field (POST)
• Returns operation counts in result

Example

const automations = [
  {
    id: "auto_123",
    name: "Updated Welcome",
    status: "active"
  },
  {
    name: "New Campaign",
    trigger: { type: "subscriber_created" },
    actions: []
  }
];

const result = await REMOTE_AUTOMATIONS_RESOURCE.set(
  automations,
  config
);

console.log(`Updated: ${result.updated}, Created: ${result.created}`);
// Updated: 1, Created: 1

LOCAL_AUTOMATIONS_RESOURCE

Handles automation operations with local JSON files.

const LOCAL_AUTOMATIONS_RESOURCE: Resource<Automation[], string[]>

Methods

get(configuration)

Reads all automations from the automations/ directory.

async get(configuration: Configuration): Promise<Automation[]>

configuration · Configuration · required

Configuration with directory path

return · Automation[]

Array of all valid automations from JSON files

• Searches for all .json files in automations/ directory
• Parses and validates each file
• Skips invalid files (logs via deserialize error)

set(value, configuration)

Writes automations as JSON files to the automations/ directory.

async set(
  value: Automation[],
  configuration: Configuration
): Promise<OperationResult>

value · Automation[] · required

Array of automations to write

configuration · Configuration · required

Configuration with directory path

return · OperationResult

Operation result with updated count

Behavior

• Creates automations/ directory if it doesn’t exist
• Generates filenames using slugified automation names
• Format: automations/{slugified-name}.json
• Overwrites existing files with same slug

Example

const automations = [
  { name: "Welcome Series", status: "active" },
  { name: "Re-Engagement", status: "paused" }
];

await LOCAL_AUTOMATIONS_RESOURCE.set(automations, config);
// Creates:
// - automations/welcome-series.json
// - automations/re-engagement.json

AUTOMATIONS_RESOURCE

Combined resource group for automation synchronization.

const AUTOMATIONS_RESOURCE: ResourceGroup<
  Automation[],
  Automation[],
  string[]
>

Properties

name · string

Resource identifier: "automations"

remote · Resource<Automation[], Automation[]>

Remote API resource handler

local · Resource<Automation[], string[]>

Local filesystem resource handler

Usage Patterns

Pull Automations from Remote

import { AUTOMATIONS_RESOURCE } from "./sync/automations.js";

const config = {
  baseUrl: "https://api.buttondown.email/v1",
  apiKey: "your-api-key",
  directory: "./buttondown-data"
};

// Fetch from API
const automations = await AUTOMATIONS_RESOURCE.remote.get(config);

// Save to local files
await AUTOMATIONS_RESOURCE.local.set(automations, config);

console.log(`Synced ${automations.length} automations`);

Push Local Changes to Remote

// Read from local files
const localAutomations = await AUTOMATIONS_RESOURCE.local.get(config);

// Push to API
const result = await AUTOMATIONS_RESOURCE.remote.set(
  localAutomations,
  config
);

console.log(`Updated: ${result.updated}, Created: ${result.created}`);

Constants

SERIALIZED_FIELDS

Array of field names included in JSON serialization:

const SERIALIZED_FIELDS: (keyof SerializedAutomation)[] = [
  "actions",
  "filters",
  "id",
  "metadata",
  "name",
  "should_evaluate_filter_after_delay",
  "status",
  "trigger"
]