API Documentation

Campaign lifecycle

Four calls take a campaign from raw data to running.

1. Create — upload your rows. The campaign is saved as a draft; no credits are charged.
2. Fields — set the sender details and the message. The campaign becomes configured.
3. Preview — optional. Render the message for one row exactly as it will be sent.
4. Submit — charge credits and start processing. The campaign becomes processing (or queued).

Processing is asynchronous. Poll campaign detail for progress, or supply a webhook at submit time to be notified when it finishes.

Statuses

Credit cost

Credits are charged once, at submit time: 2 credits per website, plus 1 more per website when AI personalization will actually run. Rows that turn out to be unreachable are partially or fully refunded automatically as they are processed.

Quick start

A complete campaign, end to end, with curl.

1 — Create the campaign

curl -X POST https://app.contactformblaster.com/api/v1/campaigns/create \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q3 Outreach",
    "rows": [
      { "site_url": "https://example-one.com", "business_name": "Example One" },
      { "site_url": "https://example-two.com", "business_name": "Example Two" }
    ]
  }'

2 — Configure campaign fields

curl -X POST https://app.contactformblaster.com/api/v1/campaigns/$CAMPAIGN_ID/fields \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "{first_name}": "John", "{last_name}": "Doe", "{full_name}": "John Doe",
      "{email}": "john@acme.com", "{phone_country_code}": "1", "{phone}": "5551234567",
      "{city}": "Austin", "{state_province}": "TX", "{country}": "USA",
      "{company_name}": "Acme Corp", "{misc_value}": "N/A",
      "{subject}": "Question for {contact_business_name}",
      "{message}": "Hi {contact_business_name}, I am {full_name} at {company_name}."
    }
  }'

3 — Preview one row

curl -X POST https://app.contactformblaster.com/api/v1/campaigns/$CAMPAIGN_ID/preview \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "sample_row_index": 0 }'

4 — Submit

curl -X POST https://app.contactformblaster.com/api/v1/campaigns/$CAMPAIGN_ID/submit \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "webhook_url": "https://your-app.com/hooks/campaign-done" }'

5 — Track progress

curl https://app.contactformblaster.com/api/v1/campaigns/$CAMPAIGN_ID \
  -H "Authorization: Bearer $API_KEY"

API keys

One key per account, shared with the web app.

Your account has exactly one API key at a time. It is the same key shown on the API Access page — generating a key in either place immediately replaces and invalidates the other. There is no grace period and no way to run two keys at once.

Generates a new key, invalidating the existing one. The request you make with the old key still succeeds — the replacement takes effect immediately afterwards.

Body parameters

{ "name": "Primary API Key" }

{
  "success": true,
  "message": "API key generated successfully",
  "data": {
    "api_key": "sk_live_new123456",
    "name": "Primary API Key",
    "created_at": "2026-05-02T12:00:00Z",
    "previous_key_invalidated": true
  }
}

api_key appears in this response and nowhere else, ever again.

Metadata about your current key. Returns 404 with API_KEY_NOT_FOUND if you have none.

Response

{
  "success": true,
  "message": "",
  "data": {
    "name": "Primary API Key",
    "masked_key": "sk_live_****3456",
    "created_at": "2026-05-02T12:00:00Z",
    "last_used_at": "2026-05-02T13:10:00Z"
  }
}

Form fields

The vocabulary available to your message templates.

Lists every field you can set on a campaign. Pass a campaign id to also get that campaign's own data columns as tokens.

Query parameters

Response

{
  "success": true,
  "message": "",
  "data": {
    "required_fields": [
      { "id": "{name}", "label": "Name" },
      { "id": "{email}", "label": "Email" }
    ],
    "optional_fields": [
      { "id": "{title}", "label": "Title" }
    ],
    "uploaded_fields": [
      { "id": "{contact_business_name}", "label": "business_name" }
    ],
    "field_presets": [
      { "id": 10, "name": "Business Info Pack" }
    ]
  }
}

Using tokens

Any field id can be embedded in {subject} or {message} and is replaced per row when the form is submitted:

"{message}": "Hi {contact_business_name}, I'm {full_name} from {company_name}."

Building a campaign

Create from your own data, map the message, preview, submit.

Creates a draft campaign from structured rows. Column names are entirely yours — there are no required keys. Each object in rows is one target website plus whatever data you want available to your message.

Body parameters

{
  "name": "Campaign A",
  "website_url_column": "site_url",
  "rows": [
    {
      "site_url": "https://site1.com",
      "business_name": "Company 1"
    },
    {
      "site_url": "https://site2.com",
      "business_name": "Company 2"
    }
  ]
}

{
  "success": true,
  "message": "Campaign created",
  "data": {
    "campaign_id": "cmp_123",
    "valid_rows": 150,
    "invalid_rows": 5,
    "duplicate_rows": 2,
    "profanity_rows_skipped": 0,
    "credits_required": 300,
    "credits_available": 500,
    "website_url_column": "site_url",
    "status": "draft"
  }
}

Rows are cleaned as they are accepted: blank and malformed URLs count toward invalid_rows, and repeat websites toward duplicate_rows (example.com, www.example.com and https://example.com/ are the same target). credits_required covers the base cost of the accepted rows; enabling AI adds 1 credit per website on top.

Sets the sender details and message content. Moves the campaign to configured. Can be called repeatedly until the campaign is submitted; each call replaces the previous configuration.

Body parameters

{
  "field_presets": 10,
  "fields": {
    "{name}": "John Doe",
    "{email}": "john@test.com",
    "{subject}": "Manual Subject",
    "{message}": "Manual message content"
  },
  "enable_ai_autopersonalization": true,
  "ai_instructions": "Write personalized outreach",
  "ai_presets": "preset_1"
}

{
  "success": true,
  "message": "Fields saved. The campaign is ready to submit.",
  "data": {
    "campaign_id": "cmp_123",
    "status": "configured",
    "ready_to_submit": true,
    "missing_required_fields": [],
    "ai_enabled": true,
    "ai_will_run": false,
    "total_websites": 150,
    "credits_required": 300,
    "credits_available": 500,
    "next_step": "POST /api/v1/campaigns/cmp_123/submit"
  }
}

The response is a readiness report. ready_to_submit tells you whether a submit would succeed right now; when it is false, missing_required_fields lists exactly what still needs a value and message spells it out — so you never have to attempt a submit to find out. credits_required is what that submit would charge, and ai_will_run reflects whether the AI credit is included (it is not when both {subject} and {message} were set manually).

How values are resolved

When more than one source supplies the same field, the winner is decided in this order:

1. Manual fields — anything in fields always wins.
2. AI output — fills {subject} and {message} when they were not set manually.
3. Preset — supplies anything neither of the above set.

So a manual {subject} with AI enabled means the AI writes the message and your subject is kept. Set both manually and AI is skipped entirely — and you are not charged the AI credit.

Length limits

Lengths are checked after tokens are resolved, since a short template can expand into a long message. Every field has a cap; most are 100 characters, with a handful of exceptions:

These are the same caps the campaign builder enforces in the web app, so a campaign configured either way behaves identically. Every field over its limit is reported at once:

{
  "success": false,
  "message": "One or more fields exceed the maximum allowed length.",
  "error_code": "FIELD_LENGTH_EXCEEDED",
  "data": {
    "fields": [
      { "field": "{message}", "max_length": 750, "actual_length": 1241 },
      { "field": "{subject}", "max_length": 100, "actual_length": 312 }
    ]
  }
}

Format validation

A few fields must be in a specific shape, because target forms will reject them otherwise: {email} must be a valid address, {phone_country_code} 1–3 digits with no plus sign, {phone} 7–15 digits (spaces, hyphens, parentheses, and a leading + are fine), and {website} a real domain or URL. Problems come back as INVALID_FIELD_VALUE with every offending field and a specific reason:

{
  "success": false,
  "message": "Invalid value for {email}, {phone_country_code}.",
  "error_code": "INVALID_FIELD_VALUE",
  "data": {
    "fields": [
      { "field": "{email}", "message": "Must be a valid email address (e.g. name@example.com)." },
      { "field": "{phone_country_code}", "message": "Must be 1 to 3 digits with no plus sign (e.g. 1 or 44)." }
    ]
  }
}

Renders the message for a single row exactly as it will be submitted — presets applied, tokens resolved, and AI run if enabled. Costs no credits.

Body parameters

{ "sample_row_index": 0 }

{
  "success": true,
  "message": "",
  "data": {
    "sample_row_index": 0,
    "website": "https://site1.com",
    "subject_preview": "Question for Company 1",
    "message_preview": "Hi Company 1, I'm John Doe..."
  }
}

Charges credits and starts processing. Only a configured campaign can be submitted, and only once.

Body parameters

{ "webhook_url": "https://example.com/webhook" }

{
  "success": true,
  "message": "Campaign submitted. Processing has started.",
  "data": {
    "campaign_id": "cmp_123",
    "status": "processing",
    "queued": false,
    "total_websites": 150,
    "credits_charged": 300,
    "credits_remaining": 200,
    "ai_enabled": false,
    "webhook_url": "https://example.com/webhook",
    "submitted_at": "2026-04-23T12:05:00Z",
    "track": {
      "detail": "GET /api/v1/campaigns/cmp_123",
      "results": "GET /api/v1/campaigns/cmp_123/sitelevelcampaignhistory"
    }
  }
}

A queued status with "queued": true is normal — the campaign starts automatically when a processing slot frees up. Nothing further is required from you.

Validation errors

Each of these reports every problem at once, so one round trip is enough to fix them all:

{
  "success": false,
  "message": "Cannot submit: 2 required fields have no value — {email}, {phone}. Set them with POST /api/v1/campaigns/cmp_123/fields, then submit again.",
  "error_code": "MISSING_REQUIRED_FIELDS",
  "data": {
    "fields": [
      { "field": "{email}", "label": "Email" },
      { "field": "{phone}", "label": "Phone" }
    ],
    "fix": "POST /api/v1/campaigns/cmp_123/fields"
  }
}

{
  "success": false,
  "message": "Insufficient credits",
  "error_code": "INSUFFICIENT_CREDITS",
  "data": {
    "credits_required": 300,
    "credits_available": 120
  }
}

Campaign controls

Pause, resume, and delete.

Pauses a processing campaign. Websites already mid-submission finish first. Credits are not refunded — they are held and consumed when you resume. Any other status returns CAMPAIGN_NOT_PROCESSING.

Response

{
  "success": true,
  "message": "Campaign paused",
  "data": { "campaign_id": "cmp_123", "status": "paused" }
}

Resumes a paused campaign where it left off; no further charge. Any other status returns CAMPAIGN_NOT_PAUSED. The response may come back queued if a slot is not free yet.

{
  "success": true,
  "message": "Campaign resumed",
  "data": { "campaign_id": "cmp_123", "status": "processing" }
}

{
  "success": true,
  "message": "Campaign queued — it will resume automatically.",
  "data": { "campaign_id": "cmp_123", "status": "queued" }
}

Permanently deletes a campaign and its rows. Only campaigns that have never been submitted (draft or configured) can be deleted; anything else returns CAMPAIGN_NOT_DELETABLE.

The path is the campaign itself, with no action segment after it — unlike /pause and /resume, which act on a campaign that continues to exist. It is the same path as campaign detail, with DELETE in place of GET.

Response

{
  "success": true,
  "message": "Campaign deleted",
  "data": { "campaign_id": "cmp_123" }
}

Campaign information

Listings, progress, and per-website results.

All your campaigns, newest first, with status, progress, and results — enough to build a dashboard without fetching each campaign individually. Accepts page and limit.

Response

{
  "success": true,
  "data": {
    "data": [
      {
        "id": "cmp_123",
        "name": "Campaign A",
        "status": "processing",
        "progress_percent": 65,
        "total_websites": 100,
        "success": 60,
        "failed": 5,
        "percent": 92,
        "created_at": "2026-04-23T12:00:00Z"
      }
    ],
    "pagination": { "page": 1, "limit": 50, "total": 320 }
  }
}

The two percentages answer different questions, so they rarely match: the example above is 65% of the way through, and 92% of what it has attempted has succeeded. percent here is the same measure as the webhook's percent, and success and failed match the progress block on campaign detail.

Full detail for one campaign: current status, a progress breakdown, and a tally of every error encountered. Safe to poll while the campaign runs.

Response

{
  "success": true,
  "data": {
    "id": "cmp_123",
    "name": "Campaign A",
    "status": "processing",
    "progress": {
      "processed": 80,
      "total": 100,
      "success": 70,
      "failed": 10,
      "percent": 80
    },
    "errors": [
      {
        "type": "No contact form was found on this website.",
        "error_code": "NO_CONTACT_FORM",
        "count": 248
      },
      {
        "type": "The website does not exist (its domain name could not be resolved).",
        "error_code": "DOMAIN_NOT_FOUND",
        "count": 145
      }
    ],
    "ai_enabled": false,
    "webhook_url": "https://example.com/webhook",
    "created_at": "2026-04-23T12:00:00Z",
    "started_at": "2026-04-23T12:05:00Z",
    "updated_at": "2026-04-23T12:50:00Z"
  }
}

The errors array is always sorted from most to least frequent, and contains every error type this campaign actually produced — it is not a fixed list, so new categories can appear over time. Match on error_code rather than type.

Per-website results, paginated, updated in real time — you do not have to wait for the campaign to finish. Each record maps back to your original data through row_index. Accepts page and limit.

Row statuses

Response

{
  "success": true,
  "data": {
    "campaign_id": "cmp_123",
    "summary": {
      "total": 100,
      "processed": 62,
      "success": 50,
      "failed": 12,
      "emails_retrieved_count": 13
    },
    "results": [
      {
        "row_index": 0,
        "website": "https://govisiondesign.com",
        "status": "success",
        "result_details": {
          "message": "Submitted",
          "fields_mapped": 6,
          "email_retrieved": [
            "info@govisiondesign.com",
            "sales@govisiondesign.com"
          ]
        },
        "processed_at": "2026-04-23T12:50:00Z"
      },
      {
        "row_index": 1,
        "website": "https://example.com",
        "status": "fail",
        "result_details": {
          "message": "No contact form was found on this website.",
          "error_code": "NO_CONTACT_FORM",
          "email_retrieved": []
        },
        "processed_at": "2026-04-23T12:52:00Z"
      },
      {
        "row_index": 2,
        "website": "https://pending-example.com",
        "status": "pending",
        "result_details": null,
        "processed_at": null
      }
    ],
    "pagination": { "page": 1, "limit": 50, "total": 100 }
  }
}

email_retrieved holds any public email addresses found on the site while looking for its contact form — available on successful and failed rows alike. emails_retrieved_count in the summary counts websites that yielded at least one address.

Billing

Balance, plans, cards, and purchases.

Your current balance, the card that would be charged, and the plans available to buy.

Response

{
  "success": true,
  "data": {
    "credits": 1200,
    "default_card_id": "card_1",
    "plans": [
      { "id": "plan_1", "name": "Starter", "credits": 1000, "price": 49 }
    ]
  }
}

Buys a credit plan, charging your default card.

Request

POST /api/v1/billing/buy
Authorization: Bearer sk_live_your_api_key_here
Idempotency-Key: unique_key_here
Content-Type: application/json

{ "plan_id": "plan_1" }

Response

{
  "success": true,
  "message": "Credits purchased successfully",
  "data": {
    "credits_added": 1000,
    "new_balance": 2200,
    "card_used": {
      "id": "card_1",
      "brand": "visa",
      "last4": "4242",
      "is_default": true
    }
  }
}

Errors

{
  "success": false,
  "message": "The card was declined.",
  "error_code": "CARD_FAILED"
}

{
  "success": false,
  "message": "No default payment method found",
  "error_code": "NO_DEFAULT_CARD"
}

Every saved card, with is_default marking the one /billing/buy will charge.

Response

{
  "success": true,
  "data": [
    { "id": "card_1", "brand": "visa", "last4": "4242", "is_default": true }
  ]
}

Makes a saved card the default — the one /billing/buy charges. Use a card_id from GET /billing/cards.

The change takes effect immediately, so the next purchase uses the new card. Setting a card that is already the default succeeds and changes nothing, which makes the call safe to retry.

Response

{
  "success": true,
  "message": "Default card updated",
  "data": {
    "card": {
      "id": "card_2",
      "brand": "mastercard",
      "last4": "1111",
      "is_default": true
    }
  }
}

An unknown card_id, or one belonging to another account, returns 404 with CARD_NOT_FOUND; the card that was default before stays default.

Webhooks

Get told when a campaign finishes, instead of polling.

Pass webhook_url when you submit a campaign and we will POST this JSON to it once the campaign reaches completed or failed:

{
  "campaign_id": "cmp_123",
  "status": "completed",
  "processed": 100,
  "success": 90,
  "failed": 10,
  "percent": 90
}

percent is the success rate — success as a share of processed, rounded to a whole number, and 0 if nothing was processed. It is not the same as progress.percent on campaign detail, which measures how far a campaign got rather than how well it did; by the time this webhook fires, that one is always 100.

The URL must be publicly reachable over http or https; private, loopback, and internal addresses are rejected at submit time with INVALID_WEBHOOK_URL.

Error codes

Every code the API can return, and what to do about it.

Authentication & limits

Campaigns

Billing

Request & server