Skip to main content

Campaigns

The /campaigns endpoint allows you to view, and modify your Dripcel campaigns.

View all campaigns​

GET /campaigns

View a list of all your campaigns.

  • 🔐 Permissions: ["campaign.read.config"]

Response​

Success

200
{
  ok: true,
  data: Campaign[]
}

View a single campaign​

GET /campaigns/:campaign_id

View a single campaign.

  • 🔐 Permissions: ["campaign.read.config"]

Response​

Success

200
{
  ok: true,
  data: Campaign
}

Error

404
{
  ok: false,
  error: "Campaign not found"
}

Campaigns V2​

Newer campaigns are stored in the Campaigns V2 model, which has a richer, nested shape than the Campaign type above. These are served on separate /v2 routes.

note

A V2 campaign is returned in full (no field projection). The format query parameter is not supported on these routes.

View all campaigns (V2)​

GET /campaigns/v2

View a list of all your V2 campaigns.

  • 🔐 Permissions: ["campaign.read.config"]

Response​

Success

200
{
  ok: true,
  data: CampaignV2[]
}

View a single campaign (V2)​

GET /campaigns/v2/:campaign_id

View a single V2 campaign.

  • 🔐 Permissions: ["campaign.read.config"]

Response​

Success

200
{
  ok: true,
  data: CampaignV2
}

Error

404
{
  ok: false,
  error: "Campaign not found"
}

The CampaignV2 type​

type CampaignV2 = {
  _id: string;
  org_id: string;

  name: string;
  active: boolean;

  /** Optional category labels for organising campaigns */
  categories: string[];

  /** At what level a contact opting out applies */
  opt_out_level: "campaign" | "org";

  targeting: {
    /** Only target contacts reachable within this many days (if set) */
    reachability_days?: number | null;

    tag_ids: {
      $in: string[];
      $nin: string[];
      /** Optional proportional distribution: tag_id -> weight (positive). When
       * set, a send draws contacts from each `$in` tag in proportion to its
       * weight. Keys must be a subset of `$in`, and must cover every `$in` tag. */
      weights?: Record<string, number>;
    };
    segment_ids: {
      $in: string[];
      $nin: string[];
    };

    events: {
      action: string;
      channel: "email" | "sms";
      source: string;
      exists?: boolean;
      value?: number;
      operator: "$eq" | "$gte" | "$lte" | "$exists";
    }[];
  };

  channels: {
    sms: {
      /** Global templates linked to this campaign */
      template_ids: string[];
      max_parts: number;
      delivery_method: string;
    };
    email: {
      /** Global templates linked to this campaign */
      template_ids: string[];
      configuration_set_name?: string;
    };
  };

  tracking_link: {
    tracksUnique: boolean;
    redirect_url: string;
    auto_redirect: boolean;
  };

  hooks: {
    hook_ids: string[];
    /** Extra template data available to hooks when triggered on this campaign */
    custom_data?: string;
  };

  recurring_sends: {
    /** The time window (hours, 0-23) to send the campaign */
    window: {
      min_hours: number;
      max_hours: number;
    };
  };

  financials?: {
    income_per_optin?: number | null;
    income_per_click?: number | null;
    income_per_sale?: number | null;
  };

  legal?: {
    consent_confirmation?: boolean;
    recommendation_confirmation?: boolean;
  };

  /** Present when the campaign is sourced from a marketplace offer */
  marketplace?: {
    offer_id: string;
    buyer_org_id: string;
  };

  optimisations?: {
    sms_template_id?: {
      auto: boolean;
      min_sends: number;
    };
  };

  createdAt: string;
  updatedAt: string;
};