This is a big question :-)

I'd like to be able to use the API to send mailings to subsets of groups.

What is the simplest way to achieve this?

Ideally I'd like to be able to define a subgroup using an SQL subquerey:

SELECT contact_id FROM {{mycustom tables}} WHERE {{my custom logic}}.

Alternatively my custom code could execute this sql and pass in an array of integer IDs: [2344, 651234, 7212334, 123512... etc] (but I'd rather the SQL filter)

We have a legacy mailer that uses custom logic to identify subset of people for distributed grass roots field organisers (GRFOs) to send emails to 10-200 people at a time.

We need a very simple mailer interface for our GRFOs as given their large number and the churn in the organisation we haven't found that exposing them to the full complexity of the CiviCRM has worked.

Combining this custom filtering with custom tokens (which we already have) and our own integrated simple mailer front ends would enable us to really rock-out with the CiviCRM mailer.

3 Answers 3


I have a suggestion for this :

In your custom code where you get the contacts use the GroupContact API and create a group and add those contacts to that group. And than using the Mailing API send the mailing by referencing that group. After sending you can delete that group. HTH.

  • 1
    When a user performs a search and chooses to "Schedule Mailing" to a handful of matching contacts, it does something similar -- it basically uses that approach, but with one difference -- instead of deleting the group, it flags the group with "is_hidden=1".
    – Tim Otten
    Commented Mar 25, 2015 at 5:34
  • 1
    thanks - I had considered that. The problem with this approach is that unsubscribes get lost Commented Mar 25, 2015 at 7:16
  • 2
    For the adhoc mailings, there's an extra notion of an "Unsubscribe" group (aka "base" group) which allows you to track unsubscribes across multiple adhoc blasts -- you just reuse the same "Unsubscribe/base" group for each blast. When passing the "group" data-structure to the API, you put each group under the heading of "include", "exclude", or "base."
    – Tim Otten
    Commented Mar 26, 2015 at 4:27

Although I think the hidden group answer is the most maintainable, it may be useful to mention another approach. CiviMail in v4.6 includes an A/B testing feature which takes a list of recipients from one group and breaks it into three smaller groups (test A, test B, and final blast). This is very similar to your problem.

You can see how the MailingAB API implements this (on top of the Mailing API) at https://github.com/civicrm/civicrm-core/blob/4.6.beta5/api/v3/MailingAB.php#L109

Unfortunately, in v4.6, the underlying BAO code is a bit overzealous about managing the mailing-records (e.g. autopopulating schedule and recipient lists in a way that matches the original CiviMail UX); the MailingAB bypasses this with the option "'_skip_evil_bao_auto_recipients_" and then manipulates the recipients more directly (CRM_Mailing_BAO_MailingAB::distributeRecipients()).

I would love see the API changed so that it's more flexible about creation-vs-recipients-schedule -- and almost did it myself in v4.6. However, the scraggly old bits are required to support the CIVICRM_CIVIMAIL_UI_LEGACY option. The CIVICRM_CIVIMAIL_UI_LEGACY option is scheduled for removal after v4.6, so that might be a good time for someone to clean it up.


I have created an extensions for sending e-mails through the API. Check https://civicrm.org/extensions/e-mail-api

A similair extension exist for sending sms through api and yes for printing pdf letters.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.