Net::CampaignMonitor - A Perl wrapper for the Campaign Monitor API.
This documentation refers to version v2.0.2.
use Net::CampaignMonitor; my $cm = Net::CampaignMonitor->new({ api_key => 'abcd1234abcd1234abcd1234', secure => 1, timeout => 300, });
Net::CampaignMonitor provides a Perl wrapper for the Campaign Monitor API.
All methods return a hash containing the Campaign Monitor response code, the headers and the actual response.
my %results = ( code => '', response => '', headers => '' );
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:
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.
Getting your clients
my $clients = $cm->account_clients();
Creating a client
my $client = $cm->account_clients(( 'CompanyName' => "ACME Limited", 'Country' => "Australia", 'TimeZone' => "(GMT+10:00) Canberra, Melbourne, Sydney" ));
Getting your billing details
my $billing_details = $cm->account_billingdetails()
Getting your API key
my $apikey = $cm->account_apikey($siteurl, $username, $password)
Getting valid countries
my $countries = $cm->account_countries();
Getting valid timezones
my $timezones = $cm->account_timezones();
Getting current date
my $systemdate = $cm->account_systemdate();
Adds a new administrator to the account. An invitation will be sent to the new administrator via email.
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);
Returns the email address of the administrator who is selected as the primary contact for this account.
my $primarycontact_email = $cm->account_getprimarycontact();
Creating a draft campaign
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, ));
Sending a draft campaign
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', ));
Sending a campaign preview
my $send_preview_campaign = $cm->campaigns_sendpreview( 'campaignid' => $campaign_id, 'PreviewRecipients' => [ 'test1@example.com', 'test2@example.com' ], 'Personalize' => 'Random', ));
Campaign summary
my $campaign_summary = $cm->campaigns_summary($campaign_id);
Campaign email client usage
my $email_client_usage = $cm->campaigns_emailclientusage($campaign_id);
Campaign lists and segments
my $campaign_listsandsegments = $cm->campaigns_listsandsegments($campaign_id);
Campaign recipients
my $campaign_recipients = $cm->campaigns_recipients ( 'campaignid' => $campaign_id, 'page' => '1', 'pagesize' => '100', 'orderfield' => 'email', 'orderdirection' => 'asc', ));
Campaign bounces
my $campaign_bounces = $cm->campaigns_bounces ( 'campaignid' => $campaign_id, 'page' => '1', 'pagesize' => '100', 'orderfield' => 'email', 'orderdirection' => 'asc', ));
Campaign opens
my $campaign_opens = $cm->campaigns_opens ( 'campaignid' => $campaign_id, 'date' => '1900-01-01', 'page' => '1', 'pagesize' => '100', 'orderfield' => 'email', 'orderdirection' => 'asc', ));
Campaign clicks
my $campaign_clicks = $cm->campaigns_clicks ( 'campaignid' => $campaign_id, 'date' => '1900-01-01', 'page' => '1', 'pagesize' => '100', 'orderfield' => 'email', 'orderdirection' => 'asc', ));
Campaign unsubscribes
my $campaign_unsubscribes = $cm->campaigns_unsubscribes ( 'campaignid' => $campaign_id, 'date' => '1900-01-01', 'page' => '1', 'pagesize' => '100', 'orderfield' => 'email', 'orderdirection' => 'asc', ));
Campaign spam complaints
my $campaign_spam = $cm->campaigns_spam ( 'campaignid' => $campaign_id, 'date' => '1900-01-01', 'page' => '1', 'pagesize' => '100', 'orderfield' => 'email', 'orderdirection' => 'asc', ));
Deleting a draft
my $campaign_delete = $cm->campaigns_delete($campaign_id);
Getting a client's details
my $client_details = $cm->client_clientid($client_id);
Getting sent campaigns
my $client_campaigns = $cm->client_campaigns($client_id);
Getting draft campaigns
my $client_drafts = $cm->client_drafts($client_id);
Getting scheduled campaigns
my $client_scheduled = $cm->client_scheduled($client_id);
Getting subscriber lists
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', ));
Getting segments
my $client_segments = $cm->client_segments($client_id);
Getting suppression list
my $client_suppressionlist = $cm->client_suppressionlist(( 'clientid' => $client_id, 'page' => '1', 'pagesize' => '100', 'orderfield' => 'email', 'orderdirection' => 'asc', ));
Suppress email addresses
my $suppressed = $cm->client_suppress(( 'EmailAddresses' => [ 'example123@example.com', 'example456@example.com' ], 'clientid' => $client_id, ));
Unsuppress an email address
my $unsuppressed = $cm->client_unsuppress(( 'email' => 'example123@example.com', 'clientid' => $client_id, ));
Getting templates
my $client_templates = $cm->client_templates($client_id);
Setting basic details
my $client_basic_details = $cm->client_setbasics(( 'clientid' => $client_id, 'CompanyName' => "ACME Limited", 'Country' => "Australia", 'TimeZone' => "(GMT+10:00) Canberra, Melbourne, Sydney", ));
Setting PAYG billing
my $client_payg = $cm->client_setpaygbilling(( 'clientid' => $client_id, 'Currency' => 'AUD', 'CanPurchaseCredits' => 'false', 'ClientPays' => 'true', 'MarkupPercentage' => '20', 'MarkupOnDelivery' => '5', 'MarkupPerRecipient' => '4', 'MarkupOnDesignSpamTest' => '3', ));
Setting monthly billing
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', ));
Deleting a client
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", ));
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);
Creating a list
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', ));
List details
my $list = $cm->list_listid($list_id);
Updating a list
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', ));
List stats
my $list_stats = $cm->list_stats($list_id);
List segments
my $list_segments = $cm->list_segments($list_id);
Active subscribers
my $list_active_subscribers = $cm->list_active(( 'listid' => $list_id, 'date' => '1900-01-01', 'page' => '1', 'pagesize' => '100', 'orderfield' => 'email', 'orderdirection' => 'asc', ));
Unconfirmed subscribers
my $unconfirmed_subscribers = $cm->list_unconfirmed(( 'listid' => $list_id, 'date' => '1900-01-01', 'page' => '1', 'pagesize' => '100', 'orderfield' => 'email', 'orderdirection' => 'asc', ));
Unsubscribed subscribers
my $list_unsubscribed_subscribers = $cm->list_unsubscribed(( 'listid' => $list_id, 'date' => '1900-01-01', 'page' => '1', 'pagesize' => '100', 'orderfield' => 'email', 'orderdirection' => 'asc', ));
Deleted subscribers
my $list_deleted_subscribers = $cm->list_deleted(( 'listid' => $list_id, 'date' => '1900-01-01', 'page' => '1', 'pagesize' => '100', 'orderfield' => 'email', 'orderdirection' => 'asc', ));
Bounced subscribers
my $list_bounced_subscribers = $cm->list_bounced(( 'listid' => $list_id, 'date' => '1900-01-01', 'page' => '1', 'pagesize' => '100', 'orderfield' => 'email', 'orderdirection' => 'asc', ));
List custom fields
my $list_customfields = $cm->list_customfields($list_id);
Creating a custom field
my $custom_field = $cm->list_customfields(( 'listid' => $list_id, 'FieldName' => 'Newsletter Format', 'DataType' => 'MultiSelectOne', 'Options' => [ "HTML", "Text" ], ));
Updating a custom field
my $updated_custom_field = $cm->list_customfields_update(( 'listid' => $list_id, 'customfieldkey' => '[NewsletterFormat]', 'FieldName' => 'Renamed Newsletter Format', 'VisibleInPreferenceCenter' => 'false', ));
Updating custom field options
my $updated_options = $cm->list_options(( 'listid' => $list_id, 'KeepExistingOptions' => 'true', 'Options' => [ "First Option", "Second Option", "Third Option" ], 'customfieldkey' => '[NewsletterFormat]', ));
Deleting a custom field
my $deleted_customfield = $cm->list_delete_customfieldkey(( 'listid' => $list_id, 'customfieldkey' => '[NewsletterFormat]', ));
Deleting a list
my $deleted_list = $cm->list_delete($list_id);
List webhooks
my $webhooks = $cm->list_webhooks($list_id);
Creating a webhook
my $webhook = $cm->list_webhooks(( 'listid' => $list_id, 'Events' => [ "Subscribe" ], 'Url' => 'http://example.com/subscribe', 'PayloadFormat' => 'json', ));
Testing a webhook
my $webhook = $cm->list_test(( 'listid' => $list_id, 'webhookid' => $webhook_id, ));
Deleting a webhook
my $deleted_webhook = $cm->list_delete_webhook(( 'listid' => $list_id, 'webhookid' => $webhook_id, ));
Activating a webhook
my $activated_webhook = $cm->list_activate(( 'listid' => $list_id, 'webhookid' => $webhook_id, ));
Deactivating a webhook
my $deactivated_webhook = $cm->list_deactivate(( 'listid' => $list_id, 'webhookid' => $webhook_id, ));
Creating a segment
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', ));
Updating a 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', ));
Getting a segment's details
my $updated_segment = $cm->segment_segmentid($segment_id);
Adding a segment rule
my $new_rules = $cm->segment_rules(( 'segmentid' => $segment_id, 'Subject' => 'Name', 'Clauses' => [ 'NOT_PROVIDED', 'EQUALS Subscriber Name' ], ));
Getting segment subscribers
my $segment_subs = $cm->segment_active(( 'segmentid' => $segment_id, 'date' => '1900-01-01', 'page' => '1', 'pagesize' => '100', 'orderfield' => 'email', 'orderdirection' => 'asc', ));
Deleting a segment
my $deleted_segment = $cm->segment_delete($segment_id);
Deleting a segment's rules
my $deleted_segment_rules = $cm->segment_delete_rules($segment_id);
Adding a subscriber
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', ));
Updating a subscriber
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' ));
Importing many subscribers
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', ));
Unsubscribing a subscriber
my $unsub_sub = $cm->subscribers_unsubscribe(( 'listid' => $list_id, 'EmailAddress' => 'subscriber@example.com', ));
Deleting a subscriber
my $deleted = $cm->subscribers_delete(( 'listid' => $list_id, 'email' => 'subscriber@example.com', ));
Getting a template
my $template = $cm->templates($template_id);
Creating a template
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', ));
Updating a template
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', ));
Deleting a template
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.
To install Net::CampaignMonitor, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Net::CampaignMonitor
CPAN shell
perl -MCPAN -e shell install Net::CampaignMonitor
For more information on module installation, please visit the detailed CPAN module installation guide.