+#next.. Delete Advertising sources?
+
+=item list_advertising_sources OPTION => VALUE, ...
+
+Lists all advertising sources.
+
+=over
+
+=item secret
+
+API Secret
+
+=back
+
+Example:
+
+ my $result = FS::API->list_advertising_sources(
+ 'secret' => 'sharingiscaring',
+ );
+
+ if ( $result->{'error'} ) {
+ die $result->{'error'};
+ } else {
+ # list advertising sources returns an array of hashes for sources.
+ print Dumper($result->{'sources'});
+ }
+
+=cut
+
+#list_advertising_sources
+sub list_advertising_sources {
+ my( $class, %opt ) = @_;
+ return _shared_secret_error() unless _check_shared_secret($opt{secret});
+
+ my @sources = qsearch('part_referral', {}, '', "")
+ or return { 'error' => 'No referrals' };
+
+ my $return = {
+ 'sources' => [ map $_->hashref, @sources ],
+ };
+
+ $return;
+}
+
+=item add_advertising_source OPTION => VALUE, ...
+
+Add a new advertising source.
+
+=over
+
+=item secret
+
+API Secret
+
+=item referral
+
+Referral name
+
+=item disabled
+
+Referral disabled, Y for disabled or nothing for enabled
+
+=item agentnum
+
+Agent ID number
+
+=item title
+
+External referral ID
+
+=back
+
+Example:
+
+ my $result = FS::API->add_advertising_source(
+ 'secret' => 'sharingiscaring',
+ 'referral' => 'test referral',
+
+ #optional
+ 'disabled' => 'Y',
+ 'agentnum' => '2', #agent id number
+ 'title' => 'test title',
+ );
+
+ if ( $result->{'error'} ) {
+ die $result->{'error'};
+ } else {
+ # add_advertising_source returns new source upon success.
+ print Dumper($result);
+ }
+
+=cut
+
+#add_advertising_source
+sub add_advertising_source {
+ my( $class, %opt ) = @_;
+ return _shared_secret_error() unless _check_shared_secret($opt{secret});
+
+ use FS::part_referral;
+
+ my $new_source = $opt{source};
+
+ my $source = new FS::part_referral $new_source;
+
+ my $error = $source->insert;
+
+ my $return = {$source->hash};
+ $return = { 'error' => $error, } if $error;
+
+ $return;
+}
+
+=item edit_advertising_source OPTION => VALUE, ...
+
+Edit a advertising source.
+
+=over
+
+=item secret
+
+API Secret
+
+=item refnum
+
+Referral number to edit
+
+=item source
+
+hash of edited source fields.
+
+=over
+
+=item referral
+
+Referral name
+
+=item disabled
+
+Referral disabled, Y for disabled or nothing for enabled
+
+=item agentnum
+
+Agent ID number
+
+=item title
+
+External referral ID
+
+=back
+
+=back
+
+Example:
+
+ my $result = FS::API->edit_advertising_source(
+ 'secret' => 'sharingiscaring',
+ 'refnum' => '4', # referral number to edit
+ 'source' => {
+ #optional
+ 'referral' => 'test referral',
+ 'disabled' => 'Y',
+ 'agentnum' => '2', #agent id number
+ 'title' => 'test title',
+ }
+ );
+
+ if ( $result->{'error'} ) {
+ die $result->{'error'};
+ } else {
+ # edit_advertising_source returns updated source upon success.
+ print Dumper($result);
+ }
+
+=cut
+
+#edit_advertising_source
+sub edit_advertising_source {
+ my( $class, %opt ) = @_;
+ return _shared_secret_error() unless _check_shared_secret($opt{secret});
+
+ use FS::part_referral;
+
+ my $refnum = $opt{refnum};
+ my $source = $opt{source};
+
+ my $old = FS::Record::qsearchs('part_referral', {'refnum' => $refnum,});
+ my $new = new FS::part_referral { $old->hash };
+
+ foreach my $key (keys %$source) {
+ $new->$key($source->{$key});
+ }
+
+ my $error = $new->replace;
+
+ my $return = {$new->hash};
+ $return = { 'error' => $error, } if $error;
+
+ $return;
+}
+
+
+=item email_optout OPTION => VALUE, ...
+
+Each e-mail address, or L<FS::cust_contact> record, has two opt-in flags:
+message_dest: recieve non-invoicing messages, and invoice_dest: recieve
+invoicing messages
+
+Use this API call to remove opt-in flags for an e-mail address
+
+=over 4
+
+=item address
+
+E-Mail address
+
+=item disable_message_dest
+
+Enabled by default:
+Set this parameter as 0 in your API call to leave the message_dest flag as is
+
+=item disable_invoice_dest
+
+Enabled by default:
+Set this parameter as 0 in your API call to leave the invoice_dest flag as is
+
+=back
+
+=cut
+
+sub email_opt_out {
+ my ($class, %opt) = @_;
+
+ return _shared_secret_error()
+ unless _check_shared_secret($opt{secret});
+
+ return {error => 'No e-mail address specified'}
+ unless $opt{address} && $opt{address} =~ /\@/;
+
+ $opt{disable_message_dest} ||= 1;
+ $opt{disable_invoice_dest} ||= 1;
+
+ my $address = FS::Record::dbh->quote($opt{address});
+
+ for my $cust_contact (
+ FS::Record::qsearch({
+ table => 'cust_contact',
+ select => 'cust_contact.*',
+ addl_from => 'LEFT JOIN contact_email USING (contactnum)',
+ extra_sql => "WHERE contact_email.emailaddress = $address",
+ })
+ ) {
+ $cust_contact->set(invoice_dest => '') if $opt{disable_invoice_dest};
+ $cust_contact->set(message_dest => '') if $opt{disable_message_dest};
+
+ my $error = $cust_contact->replace();
+ return {error => $error} if $error;
+ }
+ return;
+}