Customer Bulk Email API
6 PracBill API endpoints for customer bulk email. Base URL https://billing.pracbill.com.au/api.
Queue a bulk email campaign. Recipients are re-resolved server-side from the supplied filters, so the caller never provides addresses. Creates one `bulk_emails` row and one `bulk_emails_contacts` row per recipient and returns immediately - no mail is sent during the request; delivery is performed by the scheduled sender (modules/customer/cli_send_emails.php). Request bodies are deliberately not written to api_logs. Failures use the standard envelope with a stable `error_code`. Possible values: `invalid_key` (unknown or malformed API key), `capability_denied` (the key does not have `"bulk_email": true` in `api_keys.data`), `deptid_not_allowed` (the request supplied a department; the key department is authoritative), `invalid_request` (the body was not JSON), `attachments_not_supported` (attachments are not implemented in v1), `missing_subject`, `missing_content`, `invalid_schedule` (unparseable, impossible, or more than 90 days ahead), `no_recipients` (the selection resolved to nobody), `recipient_count_changed` (`confirm_count` no longer matches the resolved count), `too_many_recipients` (above `bulk_email_max_recipients`, default 5000), `daily_campaign_limit_reached` (above `bulk_email_max_daily_campaigns`, default 10), `duplicate_campaign` (same department and subject within 60 seconds), `create_failed` (the queue row could not be written), `not_found` (no such campaign in the key department), `campaign_completed` / `already_cancelled` (the campaign can no longer be cancelled).
POST /{api_key}/customer/bulk-email
Request body
| Field | Type | Description |
|---|---|---|
filters | array of object | Whitelisted recipient filters. Omit for every active, emailable customer in the key department. |
customer_ids | array of integer | Narrow the filtered set to these customers only. Never widens it: inactive customers, customers without a valid email, and customers in another department are still excluded. An empty array matches nobody. |
subject required | string | Stored raw; the sender HTML-encodes it at delivery time. |
content required | string | HTML body. Merge fields use {{field}} placeholders. |
scheduled_at | string | Optional Australia/Melbourne local date/time (Y-m-d, Y-m-d H:i or Y-m-d H:i:s, with T accepted in place of the space). Defaults to now. May not be more than 90 days ahead. |
confirm_count | integer | Optional guard: the recipient count a preview returned. Creation fails with recipient_count_changed if the freshly resolved count differs. |
Responses
200— Campaign queued
List the whitelisted recipient filter fields and the joins that may combine them. These are the only fields accepted by the preview and create endpoints. Failures use the standard envelope with a stable `error_code`. Possible values: `invalid_key` (unknown or malformed API key), `capability_denied` (the key does not have `"bulk_email": true` in `api_keys.data`), `deptid_not_allowed` (the request supplied a department; the key department is authoritative), `invalid_request` (the body was not JSON), `attachments_not_supported` (attachments are not implemented in v1), `missing_subject`, `missing_content`, `invalid_schedule` (unparseable, impossible, or more than 90 days ahead), `no_recipients` (the selection resolved to nobody), `recipient_count_changed` (`confirm_count` no longer matches the resolved count), `too_many_recipients` (above `bulk_email_max_recipients`, default 5000), `daily_campaign_limit_reached` (above `bulk_email_max_daily_campaigns`, default 10), `duplicate_campaign` (same department and subject within 60 seconds), `create_failed` (the queue row could not be written), `not_found` (no such campaign in the key department), `campaign_completed` / `already_cancelled` (the campaign can no longer be cancelled).
GET /{api_key}/customer/bulk-email/filters
Responses
200— Filter metadata
Campaign history for the API key department, 20 per page, newest first, each with its derived status and progress counts. Failures use the standard envelope with a stable `error_code`. Possible values: `invalid_key` (unknown or malformed API key), `capability_denied` (the key does not have `"bulk_email": true` in `api_keys.data`), `deptid_not_allowed` (the request supplied a department; the key department is authoritative), `invalid_request` (the body was not JSON), `attachments_not_supported` (attachments are not implemented in v1), `missing_subject`, `missing_content`, `invalid_schedule` (unparseable, impossible, or more than 90 days ahead), `no_recipients` (the selection resolved to nobody), `recipient_count_changed` (`confirm_count` no longer matches the resolved count), `too_many_recipients` (above `bulk_email_max_recipients`, default 5000), `daily_campaign_limit_reached` (above `bulk_email_max_daily_campaigns`, default 10), `duplicate_campaign` (same department and subject within 60 seconds), `create_failed` (the queue row could not be written), `not_found` (no such campaign in the key department), `campaign_completed` / `already_cancelled` (the campaign can no longer be cancelled).
GET /{api_key}/customer/bulk-email/page/{pageNumber}
Responses
200— Campaign history page
Resolve the recipient set for a filter selection without queueing anything. Returns the full recipient count plus a capped sample (default 25, maximum 1000), and - when both subject and content are supplied - a first-recipient merge-field render identical to what the sender will produce. Recipients are always restricted to active customers with a valid email in the API key department; `customer_ids` only narrows that set. Request and response bodies are deliberately not written to api_logs. Failures use the standard envelope with a stable `error_code`. Possible values: `invalid_key` (unknown or malformed API key), `capability_denied` (the key does not have `"bulk_email": true` in `api_keys.data`), `deptid_not_allowed` (the request supplied a department; the key department is authoritative), `invalid_request` (the body was not JSON), `attachments_not_supported` (attachments are not implemented in v1), `missing_subject`, `missing_content`, `invalid_schedule` (unparseable, impossible, or more than 90 days ahead), `no_recipients` (the selection resolved to nobody), `recipient_count_changed` (`confirm_count` no longer matches the resolved count), `too_many_recipients` (above `bulk_email_max_recipients`, default 5000), `daily_campaign_limit_reached` (above `bulk_email_max_daily_campaigns`, default 10), `duplicate_campaign` (same department and subject within 60 seconds), `create_failed` (the queue row could not be written), `not_found` (no such campaign in the key department), `campaign_completed` / `already_cancelled` (the campaign can no longer be cancelled).
POST /{api_key}/customer/bulk-email/preview
Request body
| Field | Type | Description |
|---|---|---|
filters | array of object | Whitelisted recipient filters. Omit for every active, emailable customer in the key department. |
customer_ids | array of integer | Narrow the filtered set to these customers only. Never widens it: inactive customers, customers without a valid email, and customers in another department are still excluded. An empty array matches nobody. |
sample_limit | integer | Recipients to return in the sample. Clamped to 1000. |
subject | string | Supply with content to receive a merge-field render. |
content | string | HTML body. Merge fields use {{field}} placeholders, e.g. {{company}}. |
Responses
200— Recipient preview
Status and progress for one campaign. Scoped to the API key department: another department's campaign is reported as `not_found`. Failures use the standard envelope with a stable `error_code`. Possible values: `invalid_key` (unknown or malformed API key), `capability_denied` (the key does not have `"bulk_email": true` in `api_keys.data`), `deptid_not_allowed` (the request supplied a department; the key department is authoritative), `invalid_request` (the body was not JSON), `attachments_not_supported` (attachments are not implemented in v1), `missing_subject`, `missing_content`, `invalid_schedule` (unparseable, impossible, or more than 90 days ahead), `no_recipients` (the selection resolved to nobody), `recipient_count_changed` (`confirm_count` no longer matches the resolved count), `too_many_recipients` (above `bulk_email_max_recipients`, default 5000), `daily_campaign_limit_reached` (above `bulk_email_max_daily_campaigns`, default 10), `duplicate_campaign` (same department and subject within 60 seconds), `create_failed` (the queue row could not be written), `not_found` (no such campaign in the key department), `campaign_completed` / `already_cancelled` (the campaign can no longer be cancelled).
GET /{api_key}/customer/bulk-email/{id}
Responses
200— Campaign status
Prevent any further delivery for a campaign: unsent recipients are withdrawn (soft-deleted) and the campaign is ended. Cancellation is not a recall - messages already sent cannot be retrieved, and a message the sender was transmitting when the request arrived may still be delivered. A campaign that has already completed or been cancelled is rejected. Failures use the standard envelope with a stable `error_code`. Possible values: `invalid_key` (unknown or malformed API key), `capability_denied` (the key does not have `"bulk_email": true` in `api_keys.data`), `deptid_not_allowed` (the request supplied a department; the key department is authoritative), `invalid_request` (the body was not JSON), `attachments_not_supported` (attachments are not implemented in v1), `missing_subject`, `missing_content`, `invalid_schedule` (unparseable, impossible, or more than 90 days ahead), `no_recipients` (the selection resolved to nobody), `recipient_count_changed` (`confirm_count` no longer matches the resolved count), `too_many_recipients` (above `bulk_email_max_recipients`, default 5000), `daily_campaign_limit_reached` (above `bulk_email_max_daily_campaigns`, default 10), `duplicate_campaign` (same department and subject within 60 seconds), `create_failed` (the queue row could not be written), `not_found` (no such campaign in the key department), `campaign_completed` / `already_cancelled` (the campaign can no longer be cancelled).
POST /{api_key}/customer/bulk-email/{id}/cancel
Responses
200— Campaign cancelled