DocumentationAPI Reference

Guides

Campaign setup

Build and launch a campaign end to end.

Build and launch a real campaign end to end. New here? Read Campaigns and Email sequences first.

Replace f_your_key_here with your API key and the example ids with your own.

1. Pick a mailbox

List your inboxes and copy a mailbox id to send from:

curl -sS 'https://api.getfurnace.io/v1/mailboxes' \
  -H 'Authorization: Bearer f_your_key_here'

2. Create a draft campaign

Give it a name and the mailbox it sends from:

curl -sS -X POST 'https://api.getfurnace.io/v1/campaigns' \
  -H 'Authorization: Bearer f_your_key_here' \
  -H 'Content-Type: application/json' \
  -d '
{
  "name": "Q2 Outbound",
  "mailbox_ids": [
    "c23da7b6-df4e-4d2f-b100-4bb07b7d38d7"
  ]
}
'

The response includes the new campaign’s id. Use it in the next steps.

3. Add your email sequence

Send the steps people will move through. This example sends an email, waits, then sends a follow-up:

curl -sS -X POST 'https://api.getfurnace.io/v1/campaigns/1d8dc901-3d2d-4d9f-9dcc-4f8b3aa1a1fb/flow' \
  -H 'Authorization: Bearer f_your_key_here' \
  -H 'Content-Type: application/json' \
  -d '
{
  "nodes": [
    {
      "id": "leadSource-1",
      "type": "leadSource",
      "position": {
        "x": 0,
        "y": 0
      },
      "data": {
        "label": "Lead Bucket",
        "customFieldKeys": [
          "company"
        ],
        "mappedStandardFieldKeys": [
          "email",
          "first_name",
          "last_name"
        ],
        "isRequired": true
      },
      "deletable": false
    },
    {
      "id": "email-1",
      "type": "email",
      "position": {
        "x": 220,
        "y": 0
      },
      "data": {
        "label": "Intro Email",
        "priority": false,
        "variants": [
          {
            "id": "11111111-1111-4111-8111-111111111111",
            "label": "A",
            "subject": "Quick question for {{first_name}}",
            "template": "Hi {{first_name}} - reaching out about {{custom.company}}.",
            "isActive": true,
            "order": 0
          },
          {
            "id": "11111111-1111-4111-8111-111111111112",
            "label": "B",
            "subject": "Following up for {{first_name}}",
            "template": "Hi {{first_name}} - wanted to share a quick idea for {{custom.company}}.",
            "isActive": true,
            "order": 1
          }
        ]
      }
    },
    {
      "id": "waitTime-1",
      "type": "waitTime",
      "position": {
        "x": 460,
        "y": 0
      },
      "data": {
        "label": "Wait 1 day",
        "duration": "1",
        "unit": "days",
        "wait_duration_seconds": 86400
      }
    },
    {
      "id": "email-2",
      "type": "email",
      "position": {
        "x": 700,
        "y": 0
      },
      "data": {
        "label": "Follow-up",
        "priority": false,
        "variants": [
          {
            "id": "22222222-2222-4222-8222-222222222221",
            "label": "A",
            "subject": "Bumping this for {{first_name}}",
            "template": "Hi {{first_name}} - circling back in case this is relevant for {{custom.company}}.",
            "isActive": true,
            "order": 0
          },
          {
            "id": "22222222-2222-4222-8222-222222222222",
            "label": "B",
            "subject": "Any thoughts, {{first_name}}?",
            "template": "Hi {{first_name}} - should I close the loop or send more detail?",
            "isActive": true,
            "order": 1
          }
        ]
      }
    }
  ],
  "edges": [
    {
      "id": "e1",
      "source": "leadSource-1",
      "target": "email-1"
    },
    {
      "id": "e2",
      "source": "email-1",
      "target": "waitTime-1"
    },
    {
      "id": "e3",
      "source": "waitTime-1",
      "target": "email-2"
    }
  ]
}
'

The copy uses tokens like {{first_name}} and {{custom.company}}. Any {{custom.*}} token becomes a value you provide for each person in the next step. See Email sequences.

4. Add a person

Add someone to the campaign. Include any custom fields the sequence uses:

curl -sS -X POST 'https://api.getfurnace.io/v1/campaigns/1d8dc901-3d2d-4d9f-9dcc-4f8b3aa1a1fb/leads' \
  -H 'Authorization: Bearer f_your_key_here' \
  -H 'Content-Type: application/json' \
  -d '
{
  "email": "alex@acme.com",
  "first_name": "Alex",
  "last_name": "Rivera",
  "custom_lead_data": {
    "company": "Acme Corp"
  }
}
'

Adding more people, updating, or importing in bulk is covered in Lead management.

5. Launch

Start sending. This puts everyone you added into the sequence:

curl -sS -X POST 'https://api.getfurnace.io/v1/campaigns/1d8dc901-3d2d-4d9f-9dcc-4f8b3aa1a1fb/launch' \
  -H 'Authorization: Bearer f_your_key_here' \
  -H 'Content-Type: application/json' \
  -d '{}'

The campaign is now running.

Editing after launch

While the campaign isYou canYou cannot
draftChange anything—
runningEdit email copy and timingAdd, remove, or reorder steps
pausedChange anything, then resume—
stopped—Edit anything

To add, remove, or reorder steps on a live campaign, pause it first, make the change, then resume. If you try a structural change while running, the request is rejected with a message telling you to pause.

Pause, resume, and stop through the campaign status endpoint — see the API Reference.