Sending your first campaign

In this guide, you will learn the basics of managing your campaigns in Cakemail.

Create your first campaign

Before you can send a campaign, you first need to set it up with your content and options. To do this, you can call the Create a campaign endpoint. Review the full API reference for a list of all the parameters you can pass.

curl --request POST \
  --url https://api.cakemail.dev/campaigns \
  --header 'accept: application/json' \
  --header 'authorization: Bearer [access token]' \
  --header 'content-type: application/json' \
  --data '{"audience":{"list_id":[list ID]},"tracking":{"opens":true,"clicks_html":true,"clicks_text":true},"sender":{"id":"[sender ID]"},"content":{"subject":"[subject]","html":"[HTML content]","text":"text content","encoding":"utf-8"},"name":"[campaign name]"}'

from cakemail.models import CreateCampaign, Audience, Tracking, Sender, Content

my_campaign = api.campaign.create(
    CreateCampaign(
        name='<campaign name>',
        audience=Audience(
            list_id=my_list.id
        ),
        tracking=Tracking(
            opens=true,
            clicks_html=true,
            clicks_text=true
        ),
        sender=Sender(
            id=my_sender.id
        ),
        content=Content(
            subject='<subject>',
            html='<HTML content>',
            text='<text content>',
            encoding='utf-8'
        )
    )
)

<?php

$myCampaign = $api->campaign->create([
    'create_campaign' => new \Cakemail\Lib\Model\CreateCampaign([
        'name' => '<campaign name>',
        'audience' => new \Cakemail\Lib\Model\Audience([
            'list_id' => $myList['id']
        ]),
        'tracking' => new \Cakemail\Lib\Model\Tracking([
            'opens' => true,
            'clicks_html' => true,
            'clicks_text' => true
        ]),
        'sender' => new \Cakemail\Lib\Model\Sender([
            'id' => $mySender['id']
        ]),
        'content' => new \Cakemail\Lib\Model\Content([
            'subject' => '<subject>',
            'html' => '<HTML content>',
            'text' => '<text content>',
            'encoding' => 'utf-8'
        ])
    ])
]);

This will return you a campaign ID. Your first campaign is now ready to test and send.

Render a preview

Before you send your campaign, make sure to test it. The first step in testing it is to render a preview of the campaign by calling the Render a campaign endpoint.

curl --request GET \
  --url https://api.cakemail.dev/campaigns/[campaign ID]/render \
  --header 'accept: application/json' \
  --header 'authorization: Bearer [access token]'

my_render = api.campaign.render(
    campaign_id=my_campaign.id
)

<?php

$myRender = $api->campaign->render([
    'campaign_id' => $myCampaign['id']
]);

This will return you an object with the render of both the HTML and the text versions.

Send a test email

Now that you have confirmed the render of the campaign looks good, you will want to check how it looks in an actual email client. Keep in mind that email clients don't all behave the same, so testing in more than one email client is always a good idea to ensure your campaign looks great across all of them.

To send a test email, simply call the Send a test email endpoint along with an email address.

curl --request POST \
  --url https://api.cakemail.dev/campaigns/[campaign ID]/send-test \
  --header 'accept: application/json' \
  --header 'authorization: Bearer [access token]' \
  --header 'content-type: application/json' \
  --data '{"test_email":{"email":[test email address]},"type":"merged"}'

from cakemail.models import SendTestEmail

api.campaign.send_test_email(
    campaign_id=my_campaign.id,
    send_test_email=SendTestEmail(
        email='<test email address>',
        type='merged'
    )
)

<?php

$api->campaign->sendTestEmail([
    'campaign_id' => $myCampaign['id'],
    'send_test_email' => new \Cakemail\Lib\Models\SendTestEmail([
        'email' => '<test email address>',
        'type' => 'merged'
    ])
]);

You should now receive shortly an email in your inbox containing both the HTML and the text versions of the campaign. If you want to test them separately, you can specify the parameter type with the value separated.

Schedule your campaign

You are now ready to send your campaign. In this case, we will schedule it for later. To schedule your campaign, you can call the Schedule a campaign endpoint along with a date (in the form of a UNIX timestamp).

curl --request POST \
  --url https://api.cakemail.dev/campaigns/[campaign ID]/schedule \
  --header 'accept: application/json' \
  --header 'authorization: Bearer [access token]' \
  --header 'content-type: application/json' \
  --data '{"date":[your scheduled date]}'

from cakemail.models import ScheduleCampaign

api.campaign.schedule(
    campaign_id=my_campaign.id,
    schedule_campaign=ScheduleCampaign(
        date=<your scheduled date>
    )
)

<?php

$api->campaign->schedule([
    'campaign_id' => $myCampaign['id'],
    'schedule_campaign' => new \Cakemail\Lib\Model\ScheduleCampaign([
        'date' => <your scheduled date>
    ])
]);

Your campaign will be sent to your selected audience on that date. If you want to send your campaign right now instead of scheduling it in the future, you can simply omit the date parameter.

Review your campaign report

After your campaign has been sent, you will most likely want to know how it performed. For that, you can call our Analytic API with the Show campaign report endpoint.

curl --request GET \
  --url https://api.cakemail.dev/reports/campaigns/[campaign ID] \
  --header 'accept: application/json' \
  --header 'authorization: Bearer [access token]'

my_report = api.report.get_campaign(campaign_id=my_campaign.id)

<?php

$myReport = $api->report->getCampaign([
    'campaign_id' => $myCampaign['id']
]);

This will return a handful of metrics from the open and click rate to the bounce and spam rate. Reviewing these metrics over time will allow you to create campaigns that perform better.

Get more details

In the case, you want more details regarding one or more metrics of your campaign, you can retrieve the complete logs of the campaign by calling the Show campaign logs endpoint.

curl --request GET \
  --url 'https://api.cakemail.dev/logs/campaigns/[campaign ID]?page=1&per_page=50&with_count=false' \
  --header 'accept: application/json' \
  --header 'authorization: Bearer [access token]'

my_logs = api.log.get_campaign(campaign_id=my_campaign.id)

<?php

$myLogs = $api->log->getCampaign([
    'campaign_id' => $myCampaign['id']
]);

This will return your the logs of your campaign. You can review the full API reference for more details about filtering and sorting options.

Display all your campaigns

As you send more campaigns, you will want to display the campaigns that are in your account. You can retrieve the list of campaigns in your account by calling the Show all campaigns endpoint.

curl --request GET \
  --url 'https://api.cakemail.dev/campaigns?page=1&per_page=50&with_count=false' \
  --header 'accept: application/json' \
  --header 'authorization: Bearer [access token]'

my_campaigns = api.campaign.list()

<?php

$myCampaigns = $api->campaign->list();

This will return you a list of your campaigns.

You can explore the full API reference for more advanced features in the Campaign API.