Campaigns

Create a campaign

POST /api/v1/campaigns

Creates the campaign with html as its content. It goes to a list (mail_list_uid) or to addresses typed in (addresses), not both. Run it with the run call.

Request body application/x-www-form-urlencoded
mail_list_uid string
The list to send to.
addresses array of string (email)
Instead of a list: the addresses to send to, at most 100. One string, the addresses separated by commas or new lines, works too.
name string required
subject string required
from_email string (email) required
from_name string required
reply_to string (email) required
html string required
The content of the email.
preheader string
The line shown after the subject in the inbox.
track_open boolean
Default: 1
track_click boolean
Default: 1
sign_dkim boolean
Default: 1
skip_failed_message boolean
Keep sending when a message fails.
Default: 0
custom_headers array of object
Headers added to every email, at most 10, e.g. X-Postmaster-Msgtype or Feedback-ID. Headers that build the email or decide its delivery are refused.
Responses
200 The campaign was created.
401 The token is missing or wrong (Unauthenticated.), or its user may not act on this object (Unauthorized). Without the Accept: application/json header, a missing or wrong token answers with a redirect to the sign-in page instead.
403 A field is missing or wrong (each field that failed, with its messages), or the token's user may not create a campaign ({"status": 0, "message": "Unauthorized"}).
422 The plan allows no more campaigns, both a list and addresses were sent, or the addresses were refused.
Create a campaign
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
curl -X POST 'https://your-domain/api/v1/campaigns' \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  --data-urlencode 'mail_list_uid=6adaabbf98847' \
  --data-urlencode 'addresses[]=anna@example.com' \
  --data-urlencode 'addresses[]=ben@example.com' \
  --data-urlencode 'name=November newsletter' \
  --data-urlencode 'subject=What'\''s new this month' \
  --data-urlencode 'from_email=hello@example.com' \
  --data-urlencode 'from_name=Example Team' \
  --data-urlencode 'reply_to=hello@example.com' \
  --data-urlencode 'html=<p>Hello!</p>' \
  --data-urlencode 'preheader=Three changes worth knowing about' \
  --data-urlencode 'track_open=1' \
  --data-urlencode 'track_click=1' \
  --data-urlencode 'sign_dkim=1' \
  --data-urlencode 'skip_failed_message=0' \
  --data-urlencode 'custom_headers[0][name]=X-Postmaster-Msgtype' \
  --data-urlencode 'custom_headers[0][value]=news{{ CAMPAIGN_UID }}'
1 2 3 4 5 6 7 8 9 10
$client = new Acelle\Client('https://your-domain/api/v1', 'YOUR_API_TOKEN');
$client->campaign()->create([
    'mail_list_uid' => '6adaabbf98847',
    'name' => 'November newsletter',
    'subject' => "What's new this month",
    'from_email' => 'hello@example.com',
    'from_name' => 'Example Team',
    'reply_to' => 'hello@example.com',
    'html' => '<p>Hello!</p>',
]);
Response
{
    "status": 1,
    "message": "A new campaign was added!",
    "attributes": {
        "uid": "6adaabd2b4753",
        "name": "November newsletter",
        "status": "new",
        "created_at": "2026-11-14 10:00:00"
    }
}