Skip to content

Email Campaigns

Campaign Approval

POST /api.php

This endpoint is used to approve a campaign by updating its status to 'Ready'. The campaign is identified by its unique CampaignID.

Request Body Parameters:

ParameterDescriptionRequired?
SessionIDThe ID of the user's current sessionYes
APIKeyThe user's API key. Either SessionID or APIKey must be provided.Yes
CommandCampaign.ApproveYes
CampaignIDThe unique identifier for the campaign to approveYes
bash
curl -X POST https://example.com/api.php \
  -H "Content-Type: application/json" \
  -d '{"SessionID": "your-session-id", "APIKey": "your-api-key", "Command": "Campaign.Approve", "CampaignID": "123"}'
json
{
  "Success": true,
  "ErrorCode": 0
}
json
{
  "Success": false,
  "ErrorCode": 1
}
txt
1: Missing required parameter: CampaignID
2: Campaign not found

Cancel a Campaign

POST /api.php

This endpoint is used to cancel a specific campaign. The campaign must belong to the user making the request.

Request Body Parameters:

ParameterDescriptionRequired?
SessionIDThe ID of the user's current sessionYes
APIKeyThe user's API key. Either SessionID or APIKey must be provided.Yes
CommandCampaign.CancelYes
CampaignIDThe unique identifier for the campaign to be canceledYes
bash
curl -X POST https://example.com/api.php \
  -d 'SessionID=exampleSessionId' \
  -d 'APIKey=exampleApiKey' \
  -d 'Command=Campaign.Cancel' \
  -d 'CampaignID=123'
json
{
  "Success": true,
  "ErrorCode": 0
}
json
{
  "Success": false,
  "ErrorCode": 1
}
txt
1: Missing required field: CampaignID
2: Campaign does not belong to the user or does not exist

Copy Campaign

POST /api.php

This endpoint allows you to create a copy of an existing campaign. The new campaign will be created with the status 'Draft' and all the settings from the original campaign, except for the scheduled sending information.

Request Body Parameters:

ParameterDescriptionRequired?
SessionIDThe ID of the user's current sessionYes
APIKeyThe user's API key. Either SessionID or APIKey must be provided.Yes
CommandCampaign.CopyYes
CampaignIDThe unique identifier of the campaign to be copiedYes
bash
curl -X POST https://yourdomain.com/api.php \
  -d 'SessionID=example-session-id' \
  -d 'APIKey=example-api-key' \
  -d 'Command=Campaign.Copy' \
  -d 'CampaignID=123'
json
{
  "Success": true,
  "ErrorCode": 0,
  "NewCampaignID": "456"
}
json
{
  "Success": false,
  "ErrorCode": [1],
  "ErrorText": ["Invalid source campaign"]
}
txt
1: Invalid source campaign

Create a New Campaign

POST /api.php

This endpoint is used to create a new campaign in the system. It requires the user to provide a unique campaign name.

Request Body Parameters:

ParameterDescriptionRequired?
SessionIDThe ID of the user's current sessionYes
APIKeyThe user's API key. Either SessionID or APIKey must be provided.Yes
CommandCampaign.CreateYes
CampaignNameThe name of the campaign to be createdYes
bash
curl -X POST https://example.com/api.php \
  -H "Content-Type: application/json" \
  -d '{"SessionID": "your-session-id", "APIKey": "your-api-key", "Command": "Campaign.Create", "CampaignName": "Summer Sale Campaign"}'
json
{
  "Success": true,
  "ErrorCode": 0,
  "CampaignID": 12345
}
json
{
  "Success": false,
  "ErrorCode": 1
}
txt
1: "The campaign name is required."

Retrieve Campaign Details

POST /api.php

This endpoint retrieves detailed information about a specific campaign, including statistics if requested, and calculates the campaign's email delivery throughput.

Request Body Parameters:

ParameterDescriptionRequired?
SessionIDThe ID of the user's current sessionYes
APIKeyThe user's API key. Either SessionID or APIKey must be provided.Yes
CommandCampaign.GetYes
campaignidUnique identifier for the campaign to retrieveYes
retrievestatisticsBoolean flag to indicate if campaign statistics should be retrievedNo
retrievetagsBoolean flag to indicate if campaign tags should be retrievedNo
bash
curl -X POST https://example.com/api.php \
  -d 'SessionID=exampleSessionId' \
  -d 'APIKey=exampleApiKey' \
  -d 'Command=Campaign.Get' \
  -d 'campaignid=123' \
  -d 'retrievestatistics=true' \
  -d 'retrievetags=true'
json
{
  "Success": true,
  "ErrorCode": 0,
  "Campaign": {
    "CampaignID": 123,
    "Name": "Summer Sale",
    "Status": "Active",
    "TotalSent": 10000,
    "TotalHardBounces": 100,
    "TotalSoftBounces": 50,
    "HardBounceRatio": "1.00",
    "SoftBounceRatio": "0.50",
    "Statistics": {
      "OpenStatistics": {...},
      "ClickStatistics": {...},
      ...
    },
    "Tags": ["Summer", "Sale"]
  },
  "CampaignThroughput": {
    "EmailsPerSecond": 5
  }
}
json
{
  "Success": false,
  "ErrorCode": 1,
  "ErrorMessage": "Required parameter 'campaignid' is missing."
}
txt
1: Required parameter 'campaignid' is missing.
2: The 'campaignid' parameter must be numeric.

Pause a Campaign

POST /api.php

This endpoint is used to pause an ongoing campaign. It ensures that the campaign belongs to the user and is currently in a 'Sending' state before pausing it.

Request Body Parameters:

ParameterDescriptionRequired?
SessionIDThe ID of the user's current sessionYes
APIKeyThe user's API key. Either SessionID or APIKey must be provided.Yes
CommandCampaign.PauseYes
CampaignIDThe unique identifier of the campaign to be pausedYes
bash
curl -X POST https://example.com/api.php \
  -d 'SessionID=exampleSessionId' \
  -d 'APIKey=exampleApiKey' \
  -d 'Command=Campaign.Pause' \
  -d 'CampaignID=123'
json
{
  "Success": true,
  "ErrorCode": 0
}
json
{
  "Success": false,
  "ErrorCode": 1
}
txt
1: Missing required parameter: CampaignID
2: Campaign does not belong to the user
3: Campaign is not in a 'Sending' state

Resume a Campaign

POST /api.php

This endpoint allows the user to resume a previously paused campaign. The campaign must belong to the user and must be in a 'Paused' state before it can be resumed.

Request Body Parameters:

ParameterDescriptionRequired?
SessionIDThe ID of the user's current sessionYes
APIKeyThe user's API key. Either SessionID or APIKey must be provided.Yes
CommandCampaign.ResumeYes
CampaignIDThe unique identifier of the campaign to be resumedYes
bash
curl -X POST https://example.com/api.php \
  -d 'SessionID=exampleSessionId' \
  -d 'APIKey=exampleApiKey' \
  -d 'Command=Campaign.Resume' \
  -d 'CampaignID=123'
json
{
  "Success": true,
  "ErrorCode": 0
}
json
{
  "Success": false,
  "ErrorCode": 1
}
txt
1: Missing required parameter: CampaignID
2: Campaign does not belong to the user
3: Campaign is not in a 'Paused' state

Update Campaign Details

POST /api.php

This endpoint allows you to update the details of an existing campaign. You can modify various attributes of the campaign, including its status, schedule, recipients, and more.

Request Body Parameters:

ParameterDescriptionRequired?
SessionIDThe ID of the user's current sessionYes
APIKeyThe user's API key. Either SessionID or APIKey must be provided.Yes
CommandCampaign.UpdateYes
CampaignIDUnique identifier for the campaign to be updatedYes
CampaignStatusThe new status of the campaign (e.g., Draft, Ready, Sending)No
CampaignNameThe new name for the campaignNo
RelEmailIDThe ID of the email associated with the campaignNo
ScheduleTypeThe type of scheduling for the campaign (e.g., Immediate, Future, Recursive)No
SendDateThe date when the campaign is scheduled to be sentNo
SendTimeThe time when the campaign is scheduled to be sentNo
SendTimeZoneThe timezone for the send date and timeNo
ScheduleRecDaysOfWeekDays of the week when the campaign is scheduled to recurNo
ScheduleRecDaysOfMonthDays of the month when the campaign is scheduled to recurNo
ScheduleRecMonthsMonths when the campaign is scheduled to recurNo
ScheduleRecHoursHours when the campaign is scheduled to recurNo
ScheduleRecMinutesMinutes when the campaign is scheduled to recurNo
ScheduleRecSendMaxInstanceMaximum instances for the campaign to be sent on a recurring scheduleNo
ApprovalUserExplanationExplanation from the user for campaign approvalNo
GoogleAnalyticsDomainsDomains to be tracked with Google AnalyticsNo
PublishOnRSSWhether to publish the campaign on RSS (Enabled or Disabled)No
RulesJsonBundleTarget audience in RulesJson syntax (see instructions). If this parameter is provided, RecipientListsAndSegments and Exclude_RecipientListsAndSegments will be ignored.No
RecipientListsAndSegmentsComma-separated list of recipient list and segment IDsNo
Exclude_RecipientListsAndSegmentsComma-separated list of recipient list and segment IDs to excludeNo
S2SEnabledWhether the Send-to-Send feature is enabled or notNo
bash
curl -X POST https://example.com/api.php \
  -d 'SessionID=example-session-id' \
  -d 'APIKey=example-api-key' \
  -d 'Command=Campaign.Update' \
  -d 'CampaignID=123' \
  -d 'CampaignStatus=Ready' \
  -d 'CampaignName=New Campaign Name'
json
{
  "Success": true,
  "ErrorCode": 0
}
json
{
  "Success": false,
  "ErrorCode": 1
}
txt
1: Campaign ID is required
2: Campaign does not belong to the user
3: Invalid campaign status
4: Email ID does not belong to the user
5: Invalid schedule type
6: Send date is required for future scheduled campaigns
7: Send time is required for future scheduled campaigns
8: Either days of the week or days of the month must be specified for recursive campaigns
9: Months are required for recursive campaigns
10: Hours are required for recursive campaigns
11: Minutes are required for recursive campaigns
12: Maximum instances are required for recursive campaigns
13: Timezone is required for scheduled campaigns

RulesJsonBundle Instructions

This parameter is based on RulesJson criteria syntax. You can set a detailed target audience for your email campaigns using RulesJsonbundle parameter.

Here's an example:

json
{
   "operator": "or", // The operator value should always be "or" for now
   "criteria": [
     { // For each list_id, define your RulesJson criteria
       "list_id":1,
       "operator": "and",
       "rules": [
         {
           "type": "fields",
           "field_id": "EmailAddress",
           "operator": "contains",
           "value": "user1"
         },
         {
           "type": "fields",
           "field_id": "EmailAddress",
           "operator": "contains",
           "value": ".net"
         }
       ]
     },
     {
       "list_id":2,
       "operator": "or",
       "rules": [
         {
           "type": "fields",
           "field_id": "EmailAddress",
           "operator": "contains",
           "value": "@test"
         },
         {
           "type": "fields",
           "field_id": "EmailAddress",
           "operator": "contains",
           "value": "@gmail"
         }
       ]
     }
   ]
}

Delete Campaigns

POST /api.php

This endpoint allows for the deletion of one or more campaigns associated with a user's account. The user must provide a list of campaign IDs to be deleted.

Request Body Parameters:

ParameterDescriptionRequired?
SessionIDThe ID of the user's current sessionYes
APIKeyThe user's API key. Either SessionID or APIKey must be provided.Yes
CommandCampaigns.DeleteYes
CampaignsComma-separated list of campaign IDs to be deletedYes
bash
curl -X POST https://example.com/api.php \
  -d 'SessionID=exampleSessionId' \
  -d 'APIKey=exampleApiKey' \
  -d 'Command=Campaigns.Delete' \
  -d 'Campaigns=1,2,3'
json
{
  "Success": true,
  "ErrorCode": 0,
  "ErrorText": ""
}
json
{
  "Success": false,
  "ErrorCode": {
    "campaigns": 1
  }
}
txt
1: The 'campaigns' parameter is missing or invalid.

Retrieve Campaigns

POST /api.php

This endpoint retrieves a list of campaigns based on the provided criteria. It allows for filtering, ordering, and can optionally include campaign statistics.

Request Body Parameters:

ParameterDescriptionRequired?
SessionIDThe ID of the user's current sessionYes
APIKeyThe user's API key. Either SessionID or APIKey must be provided.Yes
CommandCampaigns.GetYes
RecordsPerRequestThe number of records to retrieve per requestNo
RecordsFromThe starting point from which to retrieve recordsNo
CampaignStatusThe status of the campaigns to filter by All, Sent, Draft, Ready, Sending, Pending, Sent, Failed, ScheduledNo
SearchKeywordA keyword to search for in campaign namesNo
OrderFieldThe field to order the results byNo
OrderTypeThe type of ordering to apply (e.g., 'ASC', 'DESC')No
RetrieveTagsWhether to retrieve tags associated with the campaigns (true/false)No
TagsA comma-separated list of tag IDs to filter campaigns byNo
RetrieveStatisticsWhether to retrieve statistics for the campaigns (true/false)No
bash
curl -X POST https://example.com/api.php \
  -d 'SessionID=exampleSessionId' \
  -d 'APIKey=exampleApiKey' \
  -d 'Command=Campaigns.Get' \
  -d 'RecordsPerRequest=10' \
  -d 'RecordsFrom=0' \
  -d 'CampaignStatus=Scheduled' \
  -d 'SearchKeyword=Summer' \
  -d 'OrderField=CampaignName' \
  -d 'OrderType=ASC' \
  -d 'RetrieveTags=true' \
  -d 'Tags=1,2,3' \
  -d 'RetrieveStatistics=true'
json
{
  "Success": true,
  "ErrorCode": 0,
  "ErrorText": "",
  "Campaigns": [
    {
      "CampaignID": "123",
      "CampaignName": "Summer Sale",
      "CampaignStatus": "Active",
      // Additional campaign details...
    }
    // More campaigns...
  ],
  "TotalCampaigns": 50
}
txt
There are no error codes for this API end-point.
txt
There are no error codes for this API end-point.

Any questions? Contact us.