Net::CampaignMonitor - A Perl wrapper for the Campaign Monitor API.
This documentation refers to version v2.2.1.
use Net::CampaignMonitor;
my $cm = Net::CampaignMonitor->new({
access_token => 'your access token',
refresh_token => 'your refresh token',
secure => 1,
timeout => 300,
});
Net::CampaignMonitor provides a Perl wrapper for the Campaign Monitor API.
Get the authorization URL for your OAuth application, given the application's Client ID, Redirect URI, Permission scope, and optional state data.
my $authorize_url = Net::CampaignMonitor->authorize_url({
client_id => 'Your app client ID',
redirect_uri => 'Redirect URI for your application',
scope => 'The permission scope required by your application',
state => 'Optional state data'
});
Exchange a unique OAuth code for an OAuth access token and refresh token.
my $token_details = Net::CampaignMonitor->exchange_token(
client_id => 'Client ID for your application',
client_secret => 'Client Secret for your application',
redirect_uri => 'Redirect URI for your application',
code => 'A unique code for your user' # Get the code parameter from the query string
);
The resulting variable $token_details will be of the form:
{
'refresh_token' => 'refresh token',
'expires_in' => 1209600, # seconds until the access token expires
'access_token' => 'access token'
}
If you want to authenticate using OAuth:
my $cm = Net::CampaignMonitor->new({
access_token => 'your access token',
refresh_token => 'your refresh token',
secure => 1,
timeout => 300,
});
Or if you want to authenticate using an API key:
my $cm = Net::CampaignMonitor->new({
api_key => 'abcd1234abcd1234abcd1234',
secure => 1,
timeout => 300,
});
Construct a new Net::CampaignMonitor object. Takes an optional hash reference of config options. The options are:
access_token - The OAuth access token to use when making Campaign Monitor API requests.
refresh_token - The OAuth refresh token to use to renew access_token when it expires.
api_key - The api key for the Campaign Monitor account. If none is supplied the only function which will work is account_apikey.
secure - Set to 1 (secure) or 0 (insecure) to determine whether to use http or https. Defaults to secure.
timeout - Set the timeout for the authentication. Defaults to 600 seconds.
Refresh the current OAuth access token using the current refresh token. After making this call successfully, you will be able to continue making further API calls.
my $new_token_details = $cm->refresh_token();
The resulting variable $new_token_details will be of the form:
{
'refresh_token' => 'new refresh token',
'expires_in' => 1209600, # seconds until the new access token expires
'access_token' => 'new access token'
}
All the following methods return a hash containing the Campaign Monitor response code, the headers and the actual response.
my %results = (
code => '',
response => '',
headers => ''
);
my $clients = $cm->account_clients();
my $client = $cm->account_clients((
'CompanyName' => "ACME Limited",
'Country' => "Australia",
'TimeZone' => "(GMT+10:00) Canberra, Melbourne, Sydney"
));
my $billing_details = $cm->account_billingdetails()
my $apikey = $cm->account_apikey($siteurl, $username, $password)
my $countries = $cm->account_countries();
my $timezones = $cm->account_timezones();
my $systemdate = $cm->account_systemdate();
my $person_email = $cm->account_addadmin((
'EmailAddress' => "jane\@example.com",
'Name' => "Jane Doe"
));
Updates the email address and/or name of an administrator.
my $admin_email = $cm->account_updateadmin((
'email' => "jane\@example.com",
'EmailAddress' => "jane.new\@example.com",
'Name' => "Jane Doeman"
));
Contains a list of all (active or invited) administrators associated with a particular account.
my $admins = $cm->account_getadmins();
Returns the details of a single administrator associated with an account.
my $admin_details = $cm->account_getadmin($email);
Changes the status of an active administrator to a deleted administrator.
my $result = $cm->account_deleteadmin($admin_email);
Sets the primary contact for the account to be the administrator with the specified email address.
my $primarycontact_email = $cm->account_setprimarycontact($admin_email);
my $primarycontact_email = $cm->account_getprimarycontact();
my $external_session = $cm->account_externalsession((
'Email' => 'example@example.com',
'Chrome' => 'None',
'Url' => '/subscribers/search?search=belle@example.com',
'IntegratorID' => 'a1b2c3d4e5f6',
'ClientID' => 'aaa111bbb222ccc333'
));
my $campaign = $cm->campaigns((
'clientid' => 'b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2',
'ListIDs' => [
'a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1',
'a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1'
],
'FromName' => 'My Name',
'TextUrl' => 'http://example.com/campaigncontent/index.txt',
'Subject' => 'My Subject',
'HtmlUrl' => 'http://example.com/campaigncontent/index.html',
'SegmentIDs' => [
'a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1',
'a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1'
],
'FromEmail' => 'myemail@mydomain.com',
'Name' => 'My Campaign Name',
'ReplyTo' => 'myemail@mydomain.com',
));
The clientid must be in the hash.
Creating a campaign from a template
my $template_content = {
'Singlelines' => [
{
'Content' => "This is a heading",
'Href' => "http://example.com/"
}
],
'Multilines' => [
{
'Content' => "<p>This is example</p><p>multiline <a href=\"http://example.com\">content</a>...</p>"
}
],
'Images' => [
{
'Content' => "http://example.com/image.png",
'Alt' => "This is alt text for an image",
'Href' => "http://example.com/"
}
],
'Repeaters' => [
{
'Items' => [
(
'Layout' => "My layout",
'Singlelines' => [
{
'Content' => "This is a repeater heading",
'Href' => "http://example.com/"
}
],
'Multilines' => [
{
'Content' => "<p>This is example</p><p>multiline <a href=\"http://example.com\">content</a>...</p>"
}
],
'Images' => [
{
'Content' => "http://example.com/repeater-image.png",
'Alt' => "This is alt text for a repeater image",
'Href' => "http://example.com/"
}
]
}
]
}
]
};
The $template_content variable as defined above would be used to fill the content of a template with markup similar to the following:
<html>
<head><title>My Template</title></head>
<body>
<p><singleline>Enter heading...</singleline></p>
<div><multiline>Enter description...</multiline></div>
<img id="header-image" editable="true" width="500" />
<repeater>
<layout label="My layout">
<div class="repeater-item">
<p><singleline></singleline></p>
<div><multiline></multiline></div>
<img editable="true" width="500" />
</div>
</layout>
</repeater>
<p><unsubscribe>Unsubscribe</unsubscribe></p>
</body>
</html>
my $campaign = $cm->campaigns_fromtemplate((
'clientid' => 'b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2',
'Name' => 'My Campaign Name',
'Subject' => 'My Subject',
'FromName' => 'My Name',
'FromEmail' => 'myemail@mydomain.com',
'ReplyTo' => 'myemail@mydomain.com',
'ListIDs' => [
'a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1',
'a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1'
],
'SegmentIDs' => [
'a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1',
'a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1a1'
],
'TemplateID' => '82938273928739287329873928379283',
'TemplateContent' => $template_content,
));
The clientid must be in the hash.
my $send_campaign = $cm->campaigns_send((
'campaignid' => 'b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2',
'SendDate' => 'YYYY-MM-DD HH:MM',
'ConfirmationEmail' => 'myemail@mydomain.com',
));
The campaignid must be in the hash.
Unscheduling a scheduled campaign
my $unscheduled = $cm->campaigns_unschedule((
'campaignid' => 'b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2',
));
The campaignid must be in the hash.
my $send_preview_campaign = $cm->campaigns_sendpreview(
'campaignid' => $campaign_id,
'PreviewRecipients' => [
'test1@example.com',
'test2@example.com'
],
'Personalize' => 'Random',
));
The campaignid must be in the hash.
my $campaign_summary = $cm->campaigns_summary($campaign_id);
my $email_client_usage = $cm->campaigns_emailclientusage($campaign_id);
my $campaign_listsandsegments = $cm->campaigns_listsandsegments($campaign_id);
my $campaign_recipients = $cm->campaigns_recipients (
'campaignid' => $campaign_id,
'page' => '1',
'pagesize' => '100',
'orderfield' => 'email',
'orderdirection' => 'asc',
));
my $campaign_bounces = $cm->campaigns_bounces (
'campaignid' => $campaign_id,
'page' => '1',
'pagesize' => '100',
'orderfield' => 'email',
'orderdirection' => 'asc',
));
my $campaign_opens = $cm->campaigns_opens (
'campaignid' => $campaign_id,
'date' => '1900-01-01',
'page' => '1',
'pagesize' => '100',
'orderfield' => 'email',
'orderdirection' => 'asc',
));
my $campaign_clicks = $cm->campaigns_clicks (
'campaignid' => $campaign_id,
'date' => '1900-01-01',
'page' => '1',
'pagesize' => '100',
'orderfield' => 'email',
'orderdirection' => 'asc',
));
my $campaign_unsubscribes = $cm->campaigns_unsubscribes (
'campaignid' => $campaign_id,
'date' => '1900-01-01',
'page' => '1',
'pagesize' => '100',
'orderfield' => 'email',
'orderdirection' => 'asc',
));
my $campaign_spam = $cm->campaigns_spam (
'campaignid' => $campaign_id,
'date' => '1900-01-01',
'page' => '1',
'pagesize' => '100',
'orderfield' => 'email',
'orderdirection' => 'asc',
));
my $campaign_delete = $cm->campaigns_delete($campaign_id);
my $client_details = $cm->client_clientid($client_id);
my $client_campaigns = $cm->client_campaigns($client_id);
my $client_drafts = $cm->client_drafts($client_id);
my $client_scheduled = $cm->client_scheduled($client_id);
my $client_lists = $cm->client_lists($client_id);
Getting lists for an email address
my $lists = $cm->client_listsforemail((
'clientid' => $client_id,
'email' => 'example@example.com',
));
my $client_segments = $cm->client_segments($client_id);
my $client_suppressionlist = $cm->client_suppressionlist((
'clientid' => $client_id,
'page' => '1',
'pagesize' => '100',
'orderfield' => 'email',
'orderdirection' => 'asc',
));
my $suppressed = $cm->client_suppress((
'EmailAddresses' => [ 'example123@example.com', 'example456@example.com' ],
'clientid' => $client_id,
));
my $unsuppressed = $cm->client_unsuppress((
'email' => 'example123@example.com',
'clientid' => $client_id,
));
my $client_templates = $cm->client_templates($client_id);
my $client_basic_details = $cm->client_setbasics((
'clientid' => $client_id,
'CompanyName' => "ACME Limited",
'Country' => "Australia",
'TimeZone' => "(GMT+10:00) Canberra, Melbourne, Sydney",
));
my $client_payg = $cm->client_setpaygbilling((
'clientid' => $client_id,
'Currency' => 'AUD',
'CanPurchaseCredits' => 'false',
'ClientPays' => 'true',
'MarkupPercentage' => '20',
'MarkupOnDelivery' => '5',
'MarkupPerRecipient' => '4',
'MarkupOnDesignSpamTest' => '3',
));
my $client_monthly = $cm->client_setmonthlybilling((
'clientid' => $client_id,
'Currency' => 'AUD',
'ClientPays' => 'true',
'MarkupPercentage' => '20',
));
Transfer credits to/from a client
my $result = $cm->client_transfercredits((
'clientid' => $client_id,
'Credits' => '0',
'CanUseMyCreditsWhenTheyRunOut' => 'true',
));
my $client_deleted = $cm->client_delete($client_id);
Adds a new person to the client.
my $person_email = $cm->client_addperson((
'clientid' => $client_id,
'EmailAddress' => "joe\@example.com",
'Name' => "Joe Doe",
'AccessLevel' => 23,
'Password' => "safepassword"
));
Updates any aspect of a person including their email address, name and access level..
my $person_email = $cm->client_updateperson((
'clientid' => $client_id,
'email' => "joe\@example.com",
'EmailAddress' => "joe.new\@example.com",
'Name' => "Joe Doe",
'AccessLevel' => 23,
'Password' => "safepassword"
));
Contains a list of all (active or invited) people associated with a particular client.
my $client_access-settings = $cm->client_getpeople($client_id);
Returns the details of a single person associated with a client.
my $person_details = $cm->client_getperson((
'clientid' => $client_id,
'email' => "joe\@example.com",
));
Contains a list of all (active or invited) people associated with a particular client.
my $result = $cm->client_deleteperson((
'clientid' => $client_id,
'email' => "joe\@example.com",
));
Sets the primary contact for the client to be the person with the specified email address.
my $primarycontact_email = $cm->client_setprimarycontact((
'clientid' => $client_id,
'email' => "joe\@example.com",
));
Returns the email address of the person who is selected as the primary contact for this client.
my $primarycontact_email = $cm->client_getprimarycontact($client_id);
my $list = $cm->lists((
'clientid' => $client_id,
'Title' => 'Website Subscribers',
'UnsubscribePage' => 'http://www.example.com/unsubscribed.html',
'UnsubscribeSetting' => 'AllClientLists',
'ConfirmedOptIn' => 'false',
'ConfirmationSuccessPage' => 'http://www.example.com/joined.html',
));
my $list = $cm->list_listid($list_id);
my $updated_list = $cm->list_listid((
'listid' => $list_id,
'Title' => 'Website Subscribers',
'UnsubscribePage' => 'http://www.example.com/unsubscribed.html',
'UnsubscribeSetting' => 'AllClientLists',
'ConfirmedOptIn' => 'false',
'ConfirmationSuccessPage' => 'http://www.example.com/joined.html',
'AddUnsubscribesToSuppList' => 'true',
'ScrubActiveWithSuppList' => 'true',
));
my $list_stats = $cm->list_stats($list_id);
my $list_segments = $cm->list_segments($list_id);
my $list_active_subscribers = $cm->list_active((
'listid' => $list_id,
'date' => '1900-01-01',
'page' => '1',
'pagesize' => '100',
'orderfield' => 'email',
'orderdirection' => 'asc',
));
my $unconfirmed_subscribers = $cm->list_unconfirmed((
'listid' => $list_id,
'date' => '1900-01-01',
'page' => '1',
'pagesize' => '100',
'orderfield' => 'email',
'orderdirection' => 'asc',
));
my $list_unsubscribed_subscribers = $cm->list_unsubscribed((
'listid' => $list_id,
'date' => '1900-01-01',
'page' => '1',
'pagesize' => '100',
'orderfield' => 'email',
'orderdirection' => 'asc',
));
my $list_deleted_subscribers = $cm->list_deleted((
'listid' => $list_id,
'date' => '1900-01-01',
'page' => '1',
'pagesize' => '100',
'orderfield' => 'email',
'orderdirection' => 'asc',
));
my $list_bounced_subscribers = $cm->list_bounced((
'listid' => $list_id,
'date' => '1900-01-01',
'page' => '1',
'pagesize' => '100',
'orderfield' => 'email',
'orderdirection' => 'asc',
));
my $list_customfields = $cm->list_customfields($list_id);
my $custom_field = $cm->list_customfields((
'listid' => $list_id,
'FieldName' => 'Newsletter Format',
'DataType' => 'MultiSelectOne',
'Options' => [ "HTML", "Text" ],
));
my $updated_custom_field = $cm->list_customfields_update((
'listid' => $list_id,
'customfieldkey' => '[NewsletterFormat]',
'FieldName' => 'Renamed Newsletter Format',
'VisibleInPreferenceCenter' => 'false',
));
my $updated_options = $cm->list_options((
'listid' => $list_id,
'KeepExistingOptions' => 'true',
'Options' => [ "First Option", "Second Option", "Third Option" ],
'customfieldkey' => '[NewsletterFormat]',
));
my $deleted_customfield = $cm->list_delete_customfieldkey((
'listid' => $list_id,
'customfieldkey' => '[NewsletterFormat]',
));
my $deleted_list = $cm->list_delete($list_id);
my $webhooks = $cm->list_webhooks($list_id);
my $webhook = $cm->list_webhooks((
'listid' => $list_id,
'Events' => [ "Subscribe" ],
'Url' => 'http://example.com/subscribe',
'PayloadFormat' => 'json',
));
my $webhook = $cm->list_test((
'listid' => $list_id,
'webhookid' => $webhook_id,
));
my $deleted_webhook = $cm->list_delete_webhook((
'listid' => $list_id,
'webhookid' => $webhook_id,
));
my $activated_webhook = $cm->list_activate((
'listid' => $list_id,
'webhookid' => $webhook_id,
));
my $deactivated_webhook = $cm->list_deactivate((
'listid' => $list_id,
'webhookid' => $webhook_id,
));
my $segment = $cm->segments((
'listid' => $list_id,
'Rules' => [
{
'Subject' => 'EmailAddress',
'Clauses' => [
'CONTAINS @domain.com'
]
},
{
'Subject' => 'DateSubscribed',
'Clauses' => [
'AFTER 2009-01-01',
'EQUALS 2009-01-01'
]
},
{
'Subject' => 'DateSubscribed',
'Clauses' => [
'BEFORE 2010-01-01'
]
}
],
'Title' => 'My Segment',
));
my $updated_segment = $cm->segment_segmentid((
'segmentid' => $segment_id,
'Rules' => [
{
'Subject' => 'EmailAddress',
'Clauses' => [
'CONTAINS @domain.com'
]
},
{
'Subject' => 'DateSubscribed',
'Clauses' => [
'AFTER 2009-01-01',
'EQUALS 2009-01-01'
]
},
{
'Subject' => 'DateSubscribed',
'Clauses' => [
'BEFORE 2010-01-01'
]
}
],
'Title' => 'My Segment',
));
my $updated_segment = $cm->segment_segmentid($segment_id);
my $new_rules = $cm->segment_rules((
'segmentid' => $segment_id,
'Subject' => 'Name',
'Clauses' => [
'NOT_PROVIDED',
'EQUALS Subscriber Name'
],
));
my $segment_subs = $cm->segment_active((
'segmentid' => $segment_id,
'date' => '1900-01-01',
'page' => '1',
'pagesize' => '100',
'orderfield' => 'email',
'orderdirection' => 'asc',
));
my $deleted_segment = $cm->segment_delete($segment_id);
my $deleted_segment_rules = $cm->segment_delete_rules($segment_id);
my $added_subscriber = $cm->subscribers((
'listid' => $list_id,
'Resubscribe' => 'true',
'RestartSubscriptionBasedAutoresponders' => 'true',
'CustomFields' => [
{
'Value' => 'http://example.com',
'Key' => 'website'
},
{
'Value' => 'magic',
'Key' => 'interests'
},
{
'Value' => 'romantic walks',
'Key' => 'interests'
}
],
'Name' => 'New Subscriber',
'EmailAddress' => 'subscriber@example.com',
));
Getting a subscriber's details
my $subs_details = $cm->subscribers((
'listid' => $list_id,
'email' => 'subscriber@example.com',
));
my $updated_subscriber = $cm->subscribers_update((
'Resubscribe' => 'true',
'RestartSubscriptionBasedAutoresponders' => 'true',
'CustomFields' => [
{
'Value' => 'http://example.com',
'Key' => 'website'
},
{
'Value' => 'magic',
'Key' => 'interests'
},
{
'Value' => '',
'Key' => 'interests',
'Clear' => 'true'
}
],
'Name' => 'Renamed Subscriber',
'EmailAddress' => 'subscriber@example.com',
'listid' => $list_id,
'email' => 'subscriber@example.com'
));
my $imported_subs = $cm->subscribers_import((
'listid' => $list_id,
'Subscribers' => [
{
'CustomFields' => [
{
'Value' => 'http://example.com',
'Key' => 'website'
},
{
'Value' => 'magic',
'Key' => 'interests'
},
{
'Value' => 'romantic walks',
'Key' => '',
'Clear' => 'true'
}
],
'Name' => 'New Subscriber One',
'EmailAddress' => 'subscriber1@example.com'
},
{
'Name' => 'New Subscriber Two',
'EmailAddress' => 'subscriber2@example.com'
},
{
'Name' => 'New Subscriber Three',
'EmailAddress' => 'subscriber3@example.com'
}
],
'Resubscribe' => 'true',
'QueueSubscriptionBasedAutoResponders' => 'false',
'RestartSubscriptionBasedAutoresponders' => 'true',
));
Getting a subscriber's history
my $subs_history = $cm->subscribers_history((
'listid' => $list_id,
'email' => 'subscriber@example.com',
));
my $unsub_sub = $cm->subscribers_unsubscribe((
'listid' => $list_id,
'EmailAddress' => 'subscriber@example.com',
));
my $deleted = $cm->subscribers_delete((
'listid' => $list_id,
'email' => 'subscriber@example.com',
));
my $template = $cm->templates($template_id);
my $template = $cm->templates((
'clientid' => $client_id
'ZipFileURL' => 'http://example.com/files.zip',
'HtmlPageURL' => 'http://example.com/index.html',
'ScreenshotURL' => 'http://example.com/screenshot.jpg',
'Name' => 'Template Two',
));
my $updated_template = $cm->templates(
'templateid' => $template_id
'ZipFileURL' => 'http://example.com/files.zip',
'HtmlPageURL' => 'http://example.com/index.html',
'ScreenshotURL' => 'http://example.com/screenshot.jpg',
'Name' => 'Template Two',
));
my $deleted_template = $cm->templates_delete($template_id);
In order to run the full test suite you will need to provide an API Key. This can be done in the following way.
cpan CAMPAIGN_MONITOR_API_KEY=<your_api_key> Net::CampaignMonitor
If you do not do this almost all of the tests will be skipped.
Not quite a bug. This module uses REST::Client. REST::Client fails to install properly on Windows due to this bug. You will need to make REST::Client install without running tests to install it.
Campaign Monitor <support@campaignmonitor.com>
Jeffery Candiloro <jeffery@cpan.org>
Copyright (c) 2012, Campaign Monitor <support@campaignmonitor.com<gt>. All rights reserved.
Copyright (c) 2011, Jeffery Candiloro <jeffery@cpan.org<gt>. All rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
The full text of the license can be found in the LICENSE file included with this module.
