Bulk Email - API Reference
Bulk Email
Bulk emails represent a newsletter that will be sent to a bulk audience via a mailing list. Alternatively, a bulk email is a sequence within a campaign.
End Point URL
https://api.cms-tool.net/webapps/api/bulkemail
API Parameters and Filters
?GetURLHits=1 # List all URLs clicked and who clicked them as a nested array under UrlHits:[]
?GetQueue=1 #List all members in the email queue, and the sent time, read times , read counts, etc
Data Dictionary
| Key | Definition | Type | Format |
| autologinlinks |
Auto Login Links
If true, then login hashes are added to all links in the email to make it fast and easy for receipients to login with a single click.
|
bool
|
true/false |
| bodystyle |
body style
CSS to Include in Email
|
text
|
|
| campaignid |
Campaign ID
If this email is a step in a campaign, then it has an ID, otherwise ID=0 for one off emails
|
int
|
|
| cid |
Website ID
The ID of the website this email is connected to.
|
int
|
e.g. 123456
|
| cnt_failedsenders |
Count Failed Senders
If our mail system detects that the email was not successfully sent, then record this statistic.
|
int
|
|
| cnt_link |
Count Links Clicked
How many recipients clicked a link (or possibly how many links were clicked in total)
|
int
|
|
| cnt_read |
Count Read
How many emails have been read
|
int
|
|
| cnt_unsubscribe |
Count Unsubscribe
How many people unsubscribed
|
int
|
|
| countemails |
Count Emails Total
Count of emails that will be sent in total, including sent and unsent.
|
int
|
|
| countlefttosend |
Count Left To Send
How many emails left to send
|
int
|
|
| countperminute |
countperminute
Target speed of how many emails should be sent per minute. Large lists do not send instantly, they are drip fed at this speed, to avoid being detected as spam, or getting to many replies too quickly.
|
int
|
|
| countsent |
Count Sent
How many emails have feen sent so far
|
int
|
|
| created |
Created
Timestamp when this email was created
|
timestamp
|
e.g. 2025-12-31 23:59:59
|
| emailsize |
Email Size Bytes
How many characters in the email, or how many bytes if the email is HTML formatted including all HTML codes.
|
int
|
|
| finished |
finished
Timestamp when this email finished sending to all it's recipients (ending the job)
|
timestamp
|
e.g. 2025-12-31 23:59:59
|
| fromaddr |
From Email
The Email address used as the from address. This email must be connected to a domain name which is registered in the system.
|
text
|
|
| fromname |
From Name
The human friendly name often replaces the from address in most inboxes.
|
text
|
|
| ishtml |
Is HTML
T if this is HTML email
|
char
|
|
| jobblocked |
Job Blocked
If this job should block - System override to shutdown links and reads
|
bool
|
true/false |
| jobid |
ID
Unique ID for this email job
|
Integer (Unique ID)
|
e.g. 123456
|
| jobnotes |
Notes
Notes for the user authoring the email, as to what they plan to do with it
|
text
|
|
| lastread |
Last Read
The latest timestamp for anyone receiving and reading/opening this email
|
timestamp
|
e.g. 2025-12-31 23:59:59
|
| lastsent |
Last Sent
Last email sent
|
timestamp
|
e.g. 2025-12-31 23:59:59
|
| monitorreads |
Monitor Reads
If true then add tracking pixel to emails to detect readers.
|
char
|
|
| needresetstats |
Reset Stats Required
If this has a timestamp, then we need to reset the stats and then null this when finished.
|
timestamp
|
e.g. 2025-12-31 23:59:59
|
| nextsenddue |
Next Send Due
Timestamp when should attempt to send the next email
|
timestamp
|
e.g. 2025-12-31 23:59:59
|
| ordercount |
Order Count
Statistic of how many orders were generated from this email job
|
int
|
|
| prevjobid |
Step Previous Job ID
For email campaigns, this ID links to the previous email in the sequence.
|
int
|
|
| replyto |
Reply To Email
Email address to use as the sender/reply to. This may differ from the From address
|
text
|
|
| salestotal |
Sales Total
Total value of sales from orders that originated from this email
|
text
|
Precision: 10.2
|
| sendafterdatetime |
Send After Time
Do not send any emails before this time, for delayed jobs
|
timestamp
|
e.g. 2025-12-31 23:59:59
|
| sentby |
Sent By
The staff member ID who initiated this email to be sent , or who created the email
|
int
|
|
| started |
Started
When the job was started, to begin sending emails
|
timestamp
|
e.g. 2025-12-31 23:59:59
|
| stepdelay |
Step Delay
What interval of time should occur between steps in a campaign, eg how many days
|
interval
|
e.g. 01:00:00
|
| steporder |
Step Order
If multiple steps exist in a campaign, this controls the order of the steps
|
int
|
|
| subject |
Email Subject
Subject for the email
|
text
|
|
| targetdow |
Target DOW
Target day of week (using int DOW numbers)
|
int
|
|
| targettime |
Target Time Start
Preferred time of day to send email, to avoid that clense people do of their inbox in the morning.
|
time
|
Precision: 15.6
e.g. 23:59:59
|
| targettimeend |
Target Time End
Do not send emails after this time, and instead wait until tomorrow... eg avoid sending after 5pm to business people.
|
time
|
Precision: 15.6
e.g. 23:59:59
|
| templatebody |
Email Content
The email content
|
text
|
Usage Instructions and Examples
Description
Bulk email endpoint can be used to monitor the status of bulk emails, to create bulk emails, and to manage the recipient list.
Suggestioned Workflow for adding members to email campaigns
- Create email campaigns in the CMS (so you can edit the content and upload images etc)
- Create member records with appropriate member level / opt in (via API)
- List email jobs using this endpoint. If adding to an email campaign, then look for the first email job in the campaign, eg steporder=1 or id=firstjobid
- Use the bulk email job ID to add an array of member IDs or member emails to the queue.
- Emails will automatically send if the email job is in send mode. Email campaign jobs are usually in send mode. Whereas one of newsletters will eventually finish. One off newsletters can be restarted in the CMS. The usecase of this API is most likely for sending
Adding Emails to The Queue
The member should already have been created. See Members, The member must have an opt in status level (mbr_level >= 125 )
POST https://api.cms-tool.net/webapps/api/member
{ "mbr_name":"Test", "mbr_email":"test@test.com", "optIn": true }
You can add multiple members / emails to the queue in the array named "EmailQueue"
You only need to specify the new IDs/Emails to add, not all.
You will need the job ID, eg 1234 and member ID, eg 56789 or mbr_email eg test@test.com
POST: https://api.cms-tool.net/webapps/api/bulkemail/1234
{ "EmailQueue":[ 1234, 546, 2623, ... ] }
or via email address(es)
POST: https://api.cms-tool.net/webapps/api/bulkemail/1234
{ "EmailQueue":[ {"mbr_email":"test@test.com"}, ... ] }
Queue update results will be returned in element "QueueUpdates":[]
Adding Bulk Emails to The Queue
Use the following approach to bulk add existing recipients from the member list, where any/all filters are met. If this element is provided without filters, then all opt in subscribers are added. To prevent all being added, do not provide this element at all.
{ "id":123, "ImportRecipients":{"mbr_groupid":1234,"mbr_level":200}}
Deleting Items / Opt out
There is no way at the moment to do this via API
However, you can delete a member or change the level to 0 (= "Opt out")