API Reference - Email Campaigns

Link: https://support.brilliantdirectories.com/support/solutions/articles/12000108094

← Back to API Reference | Getting Started

Email Campaigns

Email Campaigns (stored in the email_schedule table) define bulk email sends to one or more subscriber lists. Each campaign references an email template, a target audience, and scheduling details for when the send occurs.

Model name in URL: email_schedule — DB table: email_schedule

The Email Campaign Object

FieldTypeDescription
email_idintegerUnique campaign ID (primary key, read-only)
email_namestringCampaign display name required on create
send_datestringScheduled send date (format: YYYYMMDDHHmmss); 00 for immediate
email_templatestringSlug of the email template to use for this campaign
liststextComma-separated list IDs or smart list references to send to
exclude_liststextComma-separated list IDs to exclude from the send
total_sentintegerTotal number of emails sent for this campaign (read-only)
statusintegerCampaign status: 1 draft, 2 sent, 3 scheduled, 4 sending
date_addeddatetimeDate the campaign record was created
date_updatedstringDate the campaign was last updated (format: YYYYMMDDHHmmss)
added_bystringEmail address of the admin who created the campaign
overrideintegerWhether to override unsubscribe list: 1 yes, 0 no
fromstringSender display name
from_emailstringSender email address
templateintegerWhether to use the template wrapper: 1 yes, 0 no
user_typestringRecipient type: Contact or Member
limitintegerMaximum number of recipients per send batch
is_memberintegerWhether campaign targets members only: 1 yes, 0 no
block_website_fromintegerWhether to block sends from the site's own domain: 1 yes, 0 no
website_idintegerWebsite ID this campaign belongs to
colorstringColor label for the campaign (admin UI only)
smtpstringSMTP provider to use (EG sendgrid, jangosmtp)
repeat_everyintegerRepeat interval in days; 0 for one-time send
start_datestringStart date for recurring campaigns (format: YYYYMMDDHHmmss)
end_datestringEnd date for recurring campaigns (format: YYYYMMDDHHmmss)
last_runstringDate of the most recent send (format: YYYYMMDDHHmmss)
debugintegerDebug mode flag; 0 off, non-zero enables debug logging
revision_timestamptimestampTimestamp of the last record modification (auto-managed)
schedule_datedatetimeExact datetime the campaign is scheduled to send
send_whenintegerTiming option: 0 immediately, 1 scheduled
cronjobstringCron expression for recurring sends
last_errortextLast error message encountered during sending
last_error_datedatetimeDate of the last error
category_idintegerCampaign category grouping ID
total_batch_sizeintegerTotal number of recipients in the send batch (read-only)
total_send_sizeintegerTotal emails successfully sent (read-only)
total_omit_sizeintegerTotal recipients omitted from send (unsubscribed, invalid, etc.) (read-only)
cache_datatextJSON-encoded cached campaign statistics and metadata (read-only)

List Email Campaigns

GET /api/v2/email_schedule/get

Example Request

Copy
curl -X GET "https://www.yourdomain.com/api/v2/email_schedule/get?limit=25" \
  -H "X-Api-Key: your-api-key-here"

Example Response

Copy
{
  "status": "success",
  "message": [
    {
      "email_id": "101",
      "email_name": "Spring Newsletter",
      "send_date": "00",
      "email_template": "newsletter-spring",
      "lists": "92,95",
      "exclude_lists": "",
      "total_sent": "0",
      "status": "1",
      "date_added": "0000-00-00 00:00:00",
      "date_updated": "20240401100000",
      "added_by": "admin@example.com",
      "override": "1",
      "from": "My Directory",
      "from_email": "hello@example.com",
      "template": "0",
      "user_type": "Contact",
      "limit": "1000",
      "is_member": "0",
      "block_website_from": "0",
      "website_id": "12345",
      "color": "",
      "smtp": "sendgrid",
      "repeat_every": "0",
      "start_date": "",
      "end_date": "",
      "last_run": "",
      "debug": "0",
      "revision_timestamp": "2024-04-01 10:00:00",
      "schedule_date": "0000-00-00 00:00:00",
      "send_when": "0",
      "cronjob": "",
      "last_error": "",
      "last_error_date": "0000-00-00 00:00:00",
      "category_id": "0",
      "total_batch_size": "0",
      "total_send_size": "0",
      "total_omit_size": "0",
      "cache_data": null
    }
  ],
  "total": "13",
  "current_page": 1,
  "total_pages": 1,
  "next_page": ""
}

Retrieve an Email Campaign

GET /api/v2/email_schedule/get/{email_id}

Example Request

Copy
curl -X GET "https://www.yourdomain.com/api/v2/email_schedule/get/101" \
  -H "X-Api-Key: your-api-key-here"

Example Response

Copy
{
  "status": "success",
  "message": [
    {
      "email_id": "101",
      "email_name": "Spring Newsletter",
      "send_date": "00",
      "email_template": "newsletter-spring",
      "lists": "92,95",
      "status": "1",
      "from": "My Directory",
      "from_email": "hello@example.com",
      "user_type": "Contact",
      "smtp": "sendgrid",
      "website_id": "12345",
      "revision_timestamp": "2024-04-01 10:00:00"
    }
  ],
  "total": "13",
  "current_page": 1,
  "total_pages": 1
}

Create an Email Campaign

POST /api/v2/email_schedule/create

Example Request

Copy
curl -X POST "https://www.yourdomain.com/api/v2/email_schedule/create" \
  -H "X-Api-Key: your-api-key-here" \
  -d "email_name=Spring+Newsletter" \
  -d "email_template=newsletter-spring" \
  -d "lists=92%2C95" \
  -d "from=My+Directory" \
  -d "from_email=hello%40example.com" \
  -d "user_type=Contact" \
  -d "limit=1000" \
  -d "smtp=sendgrid" \
  -d "status=1"

Example Response

Copy
{
  "status": "success",
  "message": {
    "email_id": "102",
    "email_name": "Spring Newsletter",
    "email_template": "newsletter-spring",
    "lists": "92,95",
    "from": "My Directory",
    "from_email": "hello@example.com",
    "user_type": "Contact",
    "limit": "1000",
    "smtp": "sendgrid",
    "status": "1"
  }
}

Update an Email Campaign

PUT /api/v2/email_schedule/update

Example Request

Copy
curl -X PUT "https://www.yourdomain.com/api/v2/email_schedule/update" \
  -H "X-Api-Key: your-api-key-here" \
  -d "email_id=102" \
  -d "email_name=Spring+Member+Newsletter" \
  -d "status=3"

Example Response

Copy
{
  "status": "success",
  "message": {
    "email_id": "102",
    "email_name": "Spring Member Newsletter",
    "status": "3",
    "revision_timestamp": "2024-04-02 09:00:00"
  }
}

Delete an Email Campaign

DELETE /api/v2/email_schedule/delete

Example Request

Copy
curl -X DELETE "https://www.yourdomain.com/api/v2/email_schedule/delete" \
  -H "X-Api-Key: your-api-key-here" \
  -d "email_id=102"

Example Response

Copy
{
  "status": "success",
  "message": "email_schedule record was deleted"
}