Net::CampaignMonitor - A Perl wrapper for the Campaign Monitor API.
This documentation refers to version v2.1.0.
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 => '' );
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.