civicrm_api('mailing', 'create')

[Chris Burgess]

UPDATE: See http://issues.civicrm.org/jira/browse/CRM-11023 for the patch - please test and review!

We have a need for an API call to create and schedule a mailing.  When the Org creates a press release node in Drupal, they want an email sent out to their press contacts.

This had been [url http://forum.civicrm.org/index.php/topic,10668.0.html]implemented internally[/url] via SQL inserts, but the upgrade to CiviCRM 3.4.8 broke that horribly (3.2.x SQL wasn't working on the new DB layout). Time to extend the API.

Based on the postProcess() calls in CRM/Mailing/Form/*.php I've built this which is a starter. Keen for input on validation - obviously some of the values here are hardcoded and should be dynamically loaded (eg get default site From email, Reply-To, CiviMail settings).

https://gist.github.com/2246241 or below

Code: [Select]

/**
 * Handle a create event
 *
 * @param array $params
 * @return array
 */
function civicrm_api3_mailing_create($params, $ids = array()) {
        $required = array(
                // need to have either 'groups' OR 'mailings'
                'groups',
                'subject',
                'body_html',
                // maybe extrapolate
                'name',
                'created_id',
                'body_text',
                'contact_id',
        );
        $session =& CRM_Core_Session::singleton();
        $current_user = $session->get('userID');
        $defaults = array(
                'created_date'    => date('YmdHis'),
                // load the default config settings for each
                'reply_id'        => 7,
                'unsubscribe_id'  => 5,
                'optout_id'       => 6,
                'resubscribe_id'  => 8,
                'override_verp'   => TRUE,
                'forward_replies' => FALSE,
                'open_tracking'   => TRUE,
                'url_tracking'    => TRUE,
                'visibility'      => 'User and User Admin Only',
                'replyto_email'   => 'test@example.com',
                'header_id'       => 1,
                'footer_id'       => 2,
                'from_email'      => 'test@example.com',
                'from_name'       => 'From Name',
                'msg_template_id' => NULL,
                'contact_id'      => $current_user,
                'created_id'      => $current_user,
        );
        $params = array_merge($defaults, $params);
        // dpm($params, 'with defaults');

        // expected this to work, but complains about missing param 'version'
        // civicrm_api3_verify_mandatory ($params, 'CRM_Mailing_BAO_Mailing', $required, FALSE );
        // as does this
        // civicrm_api3_verify_mandatory ($params, null, $required, FALSE );
        // le sigh

        $mailing = CRM_Mailing_BAO_Mailing::create($params, $ids);
        if (!civicrm_api3_error($mailing)) {
                $job = new CRM_Mailing_BAO_Job();
                $job->mailing_id = $mailing->id;
                $job->status = 'Scheduled';
                $job->scheduled_date = date('YmdHis');
                $job->save();
                $mailing->approval_date  = CRM_Utils_Date::isoToMySQL(date('YmdHis'));
                $mailing->approver_id = $current_user;
                $mailing->approval_status_id = 1;
                $mailing->scheduled_id = $current_user;
                $mailing->scheduled_date  = date('YmdHis');
                $mailing->created_date = CRM_Utils_Date::isoToMySQL(date('YmdHis'));
                $mailing->save();
                // dpm($job, 'job');
                // dpm($mailing, 'mailing');
        }
        return $mailing;
}


[Eileen]

Hi Chris,

This is the link I pasted into IRC - I wanted to get it onto this thread as well for other people who read it

http://wiki.civicrm.org/confluence/display/CRM/API+standards

Note that 'version' => 3 IS a required param for api v3 AND that you need to call the api using the wrapper

civicrm_api('mailing','create',$params);

Any date field that is 'understood' as being a date field will be handled by the wrapper (strtotime conversion to ISO). Because mailing is a DAO this should 'just happen' without you having to do anything.

You possibly should make 'job' a separate api & call it?

[Chris Burgess]

Thanks Eileen. Glad to have the API Standards link - I was mostly referencing the existing Mailing.php API file and I think I may have been led astray. It may be that the task of implementing Mailing API to those standards requires a bit of rework in CRM/Mailing/Form/*.php as well ... oh dear.

First things first, which is POC and something which works for the client. I've got that now - will update shortly with a post on it.

I did make a separate API method for Job as you suggest, and I also found that the recipients table needs to be filled by calling

Code: [Select]

CRM_Mailing_BAO_Mailing::getRecipients() ... for now I'm just going to leave that in the mailing create method though.

Appreciate the feedback!

[Eileen]

Where we are going with the API now is starting to look @ refactoring the BAO layer to be more consistent & easily callable - which is where you were looking at. I think this reflects the fact that the form layer has become one of, rather than THE only, way of interacting with the BAO.

[xavier]

This had been implemented by an internal developer via some SQL inserts, but the upgrade to CiviCRM 3.4.8 broke that horribly (3.2.x SQL wasn't working on the new DB layout). Time to extend the API.

I will quote you relentlessly in the forums when there is a "I'll quickly hack something with mysql queries directly"

X+

[Chris Burgess]

This had been implemented by an internal developer via some SQL inserts, but the upgrade to CiviCRM 3.4.8 broke that horribly (3.2.x SQL wasn't working on the new DB layout). Time to extend the API.

I will quote you relentlessly in the forums when there is a "I'll quickly hack something with mysql queries directly"

Please do. I was quite impressed with what he'd achieved, but it wasn't really "built to last". Well, not on top of a regularly altered DB model anyway

[Eileen]

Although..  a future-proof api method needs ... tests

[Chris Burgess]

Just following up on this - I thought I opened an issue in JIRA but can't find it.

I'd love to get this finished, but when I got deep into the BAO methods for creating a mail, they interacted directly with the form layer to obtain permissions for access to recipients and some other values. Implementing the API would have required rewriting a fair bit of the mail creation forms and BAO, and I wasn't able to commit to donating the time required to get it done. I'd still like to knock this one off if there's interest, as I think ti would be great to expose CiviCRM mailings to the API - a very powerful tool for integrating content systems.

[xavier]

Still interested

X+

[Michael McAndrew]

hey there,

thought i would pipe up here.

at the recent butcombe code sprint, Micah EFF was talking about creating an 'email' API action for 'contact'.  I appreciate that this is different from what you are dicussing here, but there might be some useful thinking to be done between the two in terms of synchronising approach / joining forces / recruiting volunteers / sharing code, etc.

[Donald Lobo]

good time to do it now

we can restructure the code and move things to the relevant BAO objects and away from the form for 4.3

lobo

[Chris Burgess]

OK, opened http://issues.civicrm.org/jira/browse/CRM-11023 for this.

[Chris Burgess]

Mailing API is working at http://issues.civicrm.org/jira/browse/CRM-11023, would appreciate feedback and testing from anyone interested in this getting committed.

[xavier]

Could you write a test? Not sure what are the params for the various apis (mailing, job, setparticipants) or if they need to be set in a specific order

Code: [Select]

+function civicrm_api3_mailing_setRecipients($params) {
+    $mailing = new CRM_Mailing_BAO_Mailing();
+    $eq = $mailing->getRecipients($params['job_id'], $params['mailing_id'], NULL, NULL, true, false);
+    return civicrm_api3_create_success($eq, $params, 'Mailing', 'setRecipients');
+}
Does it set or get the recipients?

which patch do I need to apply? only v3?

X+

[Michael McAndrew]

Hallo,

I wrote an SMS api which is kind of similar and am thinking that now might be a good time to think about api conventions for naming (and possibly other things) about these api actions.

Code: [Select]

https://github.com/michaelmcandrew/ff/blob/master/extensions/org.thirdsectordesign.chainsms/api/v3/Contact/Sms.php
I was wondering what would be better 'Contact.sms' or 'Sms.create'.  In the end, I decided on 'Contact.sms' (though I am up for changing that).

I think the difference between this and most of the other api calls is that they do something on top of / outside of the database (like sending emails, sms)  Though maybe there are some others that do similar stuff.  Wondering if you have any initial thoughts on this.

Michael