civicrm_api('mailing', 'create')

[Chris Burgess]

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

I'd like to, yes. Will discuss with Eileen this week.

I will post a sample Drupal module to go with this as well.

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?

It sets them. CiviCRM sets the mailing recipients by calling CRM_Mailing_BAO_Mailing::getRecipients().

IMO getRecipients() should call setRecipients() IF REQUIRED to populate the recipients list, but the issue of function naming in the BAO should be handled separately to this issue.

which patch do I need to apply? only v3?

Yes, just v3, they are cumulative.

[Chris Burgess]

I've updated the patch today, and we've been using it for a couple of weeks now in production. It works really well.

http://issues.civicrm.org/jira/browse/CRM-11023 - feedback welcome.

[Chris Burgess]

In lieu of documentation or tests ... here's a snippet of code to demonstrate usage.

https://gist.github.com/xurizaemon/6775471

[Erich Schulz]

hey all...

just following up this

I have a need to send individualized email to quite a few groups (currently implemented in a legacy system attached to civi)

what would suit me best if this api accepted a "to" parameter that was simply an individual, or array of contacts or even (Xavier cover your eyes) an sql statement listing the recipients

is this possible?

[Chris Burgess]

I'd probably do that by generating a group via API, then send to that group.

[Erich Schulz]

hey thanks Chris

mmm... this may all cause more refactoring than I'm up for

the current (working) code generates custom lists via sql (based on specific business rules) then individualises the messages with tokens...

I was just hoping to tap into the civi mailer at the "send this message to this contact" point

creating and syncing to custom groups, plus then needing to implement custom tokens (rather than being able to just pass in the existing message)... may all be the universe telling me to leave things alone 

[Chris Burgess]

OK so first of all, be aware that this is a Mailing API not a Mail API. As I understand CiviCRM's use of the two terms, Mailing == CiviMail bulk mails, while Mail == an email to a given contact (this is the functionality exposed by the "Send Email" option in search results and on contact screen).

So Mailing is delivered in batches from cron, provides reporting, and is targeted at groups (etc), while Mail is delivered immediately, records an activity about the email, and is targeted at individual contacts (can be several but there's some hard-coded limit AFAIK).

Tokens work in both but you probably use the two differently, and if you're not trying to send a CiviMail-type-email then this might not be the tool for you?

You should consider using this API if either or both of these is true -

* CiviMail integration offers some specific additional functionality you want, OR
* Using the API is easier than implementing your own tokenised email delivery.

Otherwise there may be better options. It would be good to see additional Mail/MessageTemplate API facilities (I know at least one site who are tapping into CRM_Core_BAO_MessageTemplates::sendTemplate() and could make use of API if it was there). That might suit you if you're trying to do personalised emails which aren't suitable for CiviMail Mailing creation?

[Eileen]

I guess the UI functionality is that you can send a mailing from a search - but you need a base group too - so I guess at some level the code in the BAO must accept a list of contact ids (provided a group is also provided)

[Chris Burgess]

For sending individual templates, see http://issues.civicrm.org/jira/browse/CRM-14154

[Erich Schulz]

Thanks Chris! - this looks really promising! and looks like it will meet my highly custom email needs

Ideally I'd like to be able to tap in at the layer that provides open tracking, and that makes a record of the sent mail

I've created a few custom tokens now (which is brilliant!)...

so now I'm thinking I also could use a function that can initiate a mailing to a smart group...

I'm imagining something like `sendMailing($template_id, $group_id);`

my use case is to send monthly update emails to local group secretaries... "here are your new members, please give them a call"

is that possible? anything close?

[Chris Burgess]

I'm not sure if the snippet above is still valid, but I think CiviCRM should be able to send a mailing to a smart group, and if so then that should do the trick?

https://gist.github.com/xurizaemon/6775471

I'd probably recommend NOT using the civicrm_api module mentioned at the bottom, just instantiate your own CiviCRM API object instead.

[Erich Schulz]

awesome Chris - that worked! thanks very much

[Erich Schulz]

but I am getting this:

Strict warning: call_user_func_array() expects parameter 1 to be a valid callback, non-static method CRM_Mailing_BAO_MailingJob::create() should not be called statically in _civicrm_api3_basic_create() (line 1002 of /var/local/www/election.greens.org.au/htdocs/profiles/es_dev/modules/contrib/civicrm/api/v3/utils.php).

just a missing `static` declaration on the class?

[Erich Schulz]

darn - Its stripping out my tokens :-(

any clues?

[Erich Schulz]

mmm figured it out...

in all the testing I've done so far I get the tokens as values

but now I'm getting them as the keys... so I hacked my custom token maker to read if there was an integer as the value and then flip the array