Overview

GET/lists

List the account lists. Returns lists newest first. Pass id to fetch one list from this same path.

curl -s "https://app.bulkresponse.com/web/api/v1/lists" \
  -H "X-Auth-Token: YOUR_API_KEY"

GET/lists/{id}

Get one list. Same record as GET /lists?id=.

curl -s "https://app.bulkresponse.com/web/api/v1/lists/{id}" \
  -H "X-Auth-Token: YOUR_API_KEY"

POST/lists

Create a list. The category must already belong to this account. Names are unique per account.

curl -s -X POST "https://app.bulkresponse.com/web/api/v1/lists" \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"listname":"listname","listcategoryid":1,"fromname":"fromname","fromemail":"fromemail","replytoemail":"replytoemail"}'

POST/lists/update

Update a list. Send only the fields that change. PUT /lists/{id} and POST /lists/{id} do the same.

curl -s -X POST "https://app.bulkresponse.com/web/api/v1/lists/update" \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":1}'

GET/list-categories

List categories. Every category on the account.

No parameters.

curl -s "https://app.bulkresponse.com/web/api/v1/list-categories" \
  -H "X-Auth-Token: YOUR_API_KEY"

POST/list-categories

Create a category. Names are unique per account.

curl -s -X POST "https://app.bulkresponse.com/web/api/v1/list-categories" \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"categoryname":"categoryname"}'

POST/list-categories/update

Update a category. PUT /list-categories/{id} does the same.

curl -s -X POST "https://app.bulkresponse.com/web/api/v1/list-categories/update" \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"categoryid":1,"categoryname":"categoryname"}'

POST/list-categories/delete

Delete a category. Refused while any list still uses it. DELETE /list-categories/{id} does the same.

curl -s -X POST "https://app.bulkresponse.com/web/api/v1/list-categories/delete" \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"categoryid":1}'

GET/subscribers

List subscribers. Always scoped to one list.

curl -s "https://app.bulkresponse.com/web/api/v1/subscribers" \
  -H "X-Auth-Token: YOUR_API_KEY"

GET/subscribers/{id}

Get one subscriber. Includes address fields and any custom fields that are set.

curl -s "https://app.bulkresponse.com/web/api/v1/subscribers/{id}" \
  -H "X-Auth-Token: YOUR_API_KEY"

POST/subscribers

Add a subscriber. Uses the same gates as a web list import. A duplicate email on the same list returns 409. A bounced address, a suppression-list match (this list or the global list), or a rejected domain returns 422. Pass resubscribe true to reactivate an unsubscribed address that is not bounced or suppressed.

curl -s -X POST "https://app.bulkresponse.com/web/api/v1/subscribers" \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"list_id":1,"email":"email"}'

POST/subscribers/bulk

Add up to 100 subscribers. One request counts as one call toward the hourly limit. Send 1 to 100 subscriber objects. A valid request returns 200 even when some rows are skipped. Nothing is saved when subscribers is missing, empty, or larger than 100. Each item uses the same checks as POST /subscribers. Result codes: added, resubscribed, duplicate, duplicate_in_request, invalid, bounced, suppressed, bad_domain, error. A later copy of an email in the same request is duplicate_in_request. A custom field this account does not have is left unsaved and named in warnings.

curl -s -X POST "https://app.bulkresponse.com/web/api/v1/subscribers/bulk" \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"list_id":1,"subscribers":[1]}'

POST/subscribers/update

Update a subscriber. PUT /subscribers/{id} does the same. List counts are refreshed.

curl -s -X POST "https://app.bulkresponse.com/web/api/v1/subscribers/update" \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subscriber_id":1}'

POST/subscribers/delete

Delete a subscriber. Removes the row. DELETE /subscribers/{id} does the same.

curl -s -X POST "https://app.bulkresponse.com/web/api/v1/subscribers/delete" \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subscriber_id":1}'

POST/subscribers/unsubscribe

Unsubscribe. Send subscriber_id, or both list_id and email. Calling it again on an unsubscribed address succeeds.

curl -s -X POST "https://app.bulkresponse.com/web/api/v1/subscribers/unsubscribe" \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json"

GET/suppressions

List suppression entries. Returns this account's entries, newest first. Pass id to fetch one entry. System-wide rows are not included.

curl -s "https://app.bulkresponse.com/web/api/v1/suppressions" \
  -H "X-Auth-Token: YOUR_API_KEY"

GET/suppressions/{id}

Get one suppression entry. Same record as GET /suppressions?id=.

curl -s "https://app.bulkresponse.com/web/api/v1/suppressions/{id}" \
  -H "X-Auth-Token: YOUR_API_KEY"

POST/suppressions

Add suppression entries. Adds one or many emails or domains. Duplicates on the same list are skipped. Each new row is type gu and source api. At most 1000 entries per call.

curl -s -X POST "https://app.bulkresponse.com/web/api/v1/suppressions" \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"list_id":"list_id"}'

POST/suppressions/update

Update a suppression entry. Change the email, domain, or list. PUT /suppressions/{id} does the same. A duplicate on the destination list returns 409.

curl -s -X POST "https://app.bulkresponse.com/web/api/v1/suppressions/update" \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":1}'

POST/suppressions/delete

Remove suppression entries. Send id, ids, or entries with list_id. DELETE /suppressions/{id} removes that one entry. Only rows on this account are removed.

curl -s -X POST "https://app.bulkresponse.com/web/api/v1/suppressions/delete" \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json"

GET/campaigns

List campaigns. List rows omit HTML. Pass id to fetch one campaign, including HTML, from this path.

curl -s "https://app.bulkresponse.com/web/api/v1/campaigns" \
  -H "X-Auth-Token: YOUR_API_KEY"

GET/campaigns/{id}

Get one campaign. Includes html and text.

curl -s "https://app.bulkresponse.com/web/api/v1/campaigns/{id}" \
  -H "X-Auth-Token: YOUR_API_KEY"

POST/campaigns

Create a campaign. The campaign is active unless you pass active 0. Subject, html, and text may contain placeholders and spintax. The sender fills placeholders for each recipient and picks one spintax option per recipient.

Placeholders

Put these tags in the subject, HTML, or text. The sender replaces each one with that recipient's value.

Custom fields

A custom field uses the field name stored on the list, with the same spelling and case, wrapped in percent signs. A field named Company is %%Company%%. A field named industry is %%industry%%. These tags work in the subject, the HTML body, and the text body. An empty subscriber value is left blank.

Subject placeholders

A subject uses the same tags. Each recipient sees their own values.

%%first_name%%, a note for %%city%%

Hi %%first_name%% %%last_name%%

Spintax

Randomization picks one option for each recipient when the message is sent. Put it in the subject, the HTML body, or the text body. The block starts with {{RANDOM | and ends with }}. Separate options with a vertical bar. A placeholder inside an option is filled after the option is chosen.

{{RANDOM |Hi|Hello|Hey}} %%first_name%%,

{{RANDOM |We can help with|A short note about|An idea for}} {{RANDOM |delivery|list growth|inbox placement}}.

Subject randomization

A subject can pick one phrase per recipient. Placeholders in that subject are filled after the phrase is chosen.

{{RANDOM |Quick question|A short note|Following up}}, %%first_name%%

{{RANDOM |Hi|Hello|Hey}} %%first_name%%, your %%city%% update

{{RANDOM |Hi {{RANDOM |there|friend}}|Hello}} %%first_name%%

{{RANDOM |Hi|Hello}} {{RANDOM |there|friend}}, %%first_name%%

curl -s -X POST "https://app.bulkresponse.com/web/api/v1/campaigns" \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"name","subject":"subject"}'

POST/campaigns/update

Update a campaign. PUT /campaigns/{id} does the same.

curl -s -X POST "https://app.bulkresponse.com/web/api/v1/campaigns/update" \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"campaign_id":1}'

POST/campaigns/delete

Delete a campaign. Refused while a send for it is in progress or scheduled. DELETE /campaigns/{id} does the same.

curl -s -X POST "https://app.bulkresponse.com/web/api/v1/campaigns/delete" \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"campaign_id":1}'

POST/campaigns/send

Send now. Queues every confirmed subscriber (status c) on the lists. The call stays open until the queue is built. Lists that are being cleaned are rejected. The from name cannot contain BulkResponse.

curl -s -X POST "https://app.bulkresponse.com/web/api/v1/campaigns/send" \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"campaign_id":1,"list_ids":[1]}'

POST/campaigns/schedule

Schedule a send. Same fields as send, plus send_at. The job stays scheduled (status 4) until that time, then the mailer moves it to in progress. The default is 5 schedule requests per UTC day, unless an admin set a different cap on the account.

curl -s -X POST "https://app.bulkresponse.com/web/api/v1/campaigns/schedule" \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"campaign_id":1,"list_ids":[1],"send_at":"send_at"}'

POST/campaigns/pause

Pause a send. Pauses in-progress (1) and scheduled (4) jobs. A finished send cannot be paused.

curl -s -X POST "https://app.bulkresponse.com/web/api/v1/campaigns/pause" \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json"

POST/campaigns/resume

Resume a send. A future job returns to scheduled. A job whose start time has passed returns to in progress.

curl -s -X POST "https://app.bulkresponse.com/web/api/v1/campaigns/resume" \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json"

GET/jobs

List jobs. Newest first. The HTML and text of the message are not included. Pass id to fetch one job from this same path.

curl -s "https://app.bulkresponse.com/web/api/v1/jobs" \
  -H "X-Auth-Token: YOUR_API_KEY"

GET/jobs/{id}

Get one job. Same record as GET /jobs?id=.

curl -s "https://app.bulkresponse.com/web/api/v1/jobs/{id}" \
  -H "X-Auth-Token: YOUR_API_KEY"

POST/jobs/pause

Pause a job. Pauses an in-progress (1) or scheduled (4) job. A finished job cannot be paused.

curl -s -X POST "https://app.bulkresponse.com/web/api/v1/jobs/pause" \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"job_id":1}'

POST/jobs/resume

Resume a job. A future job returns to scheduled. A job whose start time has passed returns to in progress.

curl -s -X POST "https://app.bulkresponse.com/web/api/v1/jobs/resume" \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"job_id":1}'

GET/stats/account

Account stats. Lists, confirmed subscribers, campaigns, autoresponders, sends in progress, credits, and this calendar month’s new subscribers, opens, and clicks.

No parameters.

curl -s "https://app.bulkresponse.com/web/api/v1/stats/account" \
  -H "X-Auth-Token: YOUR_API_KEY"

GET/stats/campaign

Campaign stats. One row per send: size, sent count, opens, clicks, bounces, unsubscribes, and rates.

curl -s "https://app.bulkresponse.com/web/api/v1/stats/campaign" \
  -H "X-Auth-Token: YOUR_API_KEY"

GET/stats/list

List stats. Stored counts plus a live count by subscriber status.

curl -s "https://app.bulkresponse.com/web/api/v1/stats/list" \
  -H "X-Auth-Token: YOUR_API_KEY"

GET/stats/autoresponder

Autoresponder stats. Sent, delivered, opens, clicks, bounces, unsubscribes, and rates for each autoresponder. Rates use the same counts as the autoresponder screen.

curl -s "https://app.bulkresponse.com/web/api/v1/stats/autoresponder" \
  -H "X-Auth-Token: YOUR_API_KEY"

GET/autoresponders

List autoresponders. List rows omit HTML. Pass id to include HTML on this path.

curl -s "https://app.bulkresponse.com/web/api/v1/autoresponders" \
  -H "X-Auth-Token: YOUR_API_KEY"

GET/autoresponders/{id}

Get one autoresponder. Includes html, text, tracking flags, and the bounce address.

curl -s "https://app.bulkresponse.com/web/api/v1/autoresponders/{id}" \
  -H "X-Auth-Token: YOUR_API_KEY"

POST/autoresponders

Create an autoresponder. From name and from email are copied from the list when you omit them. Active by default.

curl -s -X POST "https://app.bulkresponse.com/web/api/v1/autoresponders" \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"list_id":1,"name":"name","subject":"subject"}'

POST/autoresponders/update

Update an autoresponder. PUT /autoresponders/{id} does the same. Send only the fields that change.

curl -s -X POST "https://app.bulkresponse.com/web/api/v1/autoresponders/update" \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"autoresponder_id":1}'

POST/autoresponders/delete

Delete an autoresponder. DELETE /autoresponders/{id} does the same.

curl -s -X POST "https://app.bulkresponse.com/web/api/v1/autoresponders/delete" \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"autoresponder_id":1}'

POST/autoresponders/activate

Activate an autoresponder. Turns sending back on.

curl -s -X POST "https://app.bulkresponse.com/web/api/v1/autoresponders/activate" \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"autoresponder_id":1}'

POST/autoresponders/pause

Pause an autoresponder. Stops further sends from this autoresponder.

curl -s -X POST "https://app.bulkresponse.com/web/api/v1/autoresponders/pause" \
  -H "X-Auth-Token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"autoresponder_id":1}'