Mailgun API: Batch Sending vs. Individual Calls

Question

Background

We're building an application that will process & send emails via Mailgun. These are sometimes one-off messages, initiated by a transaction. Some emails, though, will be sent to 30k+ at once.

Eg, a newsletter to all members.

Considerations

Mailgun offers a Batch Sending option with their API. Using "Recipient Variables", you can include dynamic values that are paired with a particular user.

This Batch Sending functionality is limited, however. You cannot send more than 1,000 recipients per request, which means we have to iterate through a recipient list (on our database) for each set of 1,000. Mailgun provides an example of how this might work, using Python (scroll about 2/3 down).

Question

Are there any advantages to batch sending (ie, sending an email to a group of recipients through a single API call, using recipient variables) as opposed to making our own loop, variable substitutions and individual API calls?

I assume this is more taxing on our server, as it would be processing each message itself, instead of just offloading all that data to Mailgun's server for heavy-lifting on their end. But I also like the flexibility & simplicity of handling that on our end and sending a "fully-rendered" message to Mailgun, one at a time, without having to iterate 1k at a time.

Any thoughts on best practices, or considerations we should take into account?

Answer 1

Stumbled onto this today, and felt it provided a pretty good summary/answer for my original question. I wanted to post this as an answer, in case anybody else has this question and hasn't found this Mailgun post. Straight from the horse's mouth, too. The nutshell version:

For PHP, at least, the SDK has a Mailgun class, with a BatchMessage() method. This actually handles the counting of recipients for you, so you can just queue up as many email addresses as you want (ie, more than 1k) and Mailgun will fire off to the API endpoint as needed. Pretty slick!

Here's their original wording, plus a link to the page.
Sending a message with Mailgun PHP SDK + Batch Message:

Batch Message

In addition to Message Builder, we have Batch Message. This class allows you to build a message and submit a template message in batches, up to 1,000 recipients per post. The benefit of using this class is that the recipients tally is monitored and will automatically submit the message to the endpoint when you've added the 1,000th recipient. This means you can build your message and begin iterating through your database. Forget about sending the message, the SDK will keep track of posting to the API when necessary.

// First, instantiate the SDK with your API credentials and define your domain.

$mgClient = new Mailgun("key-example");
$domain = "example.com";

// Next, instantiate a Message Builder object from the SDK, pass in your sending domain.  

$batchMsg = $mgClient->BatchMessage($domain);

// Define the from address.

$batchMsg->setFromAddress("[email protected]", 
                          array("first"=>"Dwight", "last" => "Schrute"));
// Define the subject. 

$batchMsg->setSubject("Help!");

// Define the body of the message.

$batchMsg->setTextBody("The printer is on fire!");

// Next, let's add a few recipients to the batch job.
$batchMsg->addToRecipient("[email protected]", 
                          array("first" => "pam", "last" => "Beesly"));
$batchMsg->addToRecipient("[email protected]", 
                          array("first" => "Jim", "last" => "Halpert"));
$batchMsg->addToRecipient("[email protected]", 
                          array("first" => "Andy", "last" => "Bernard"));
// ...etc...etc...
// After 1,000 recipeints, 
// Batch Message will automatically post your message to the messages endpoint. 

// Call finalize() to send any remaining recipients still in the buffer.

$batchMsg->finalize();

Answer 2

The answer of @cdwyer and @nikoshr is very helpful, but bit legacy. Used methods in the example are deprecated. Here is current usage of lib:

    $batchMessage = $this->mailgun->messages()->getBatchMessage('mydomain.com');


    $batchMessage->setFromAddress('[email protected]');
    $batchMessage->setReplyToAddress('[email protected]');
    $batchMessage->setSubject('Contact form | Company');
    $batchMessage->setHtmlBody('<html>...</html>');

    foreach ($recipients as $recipient) {
        $batchMessage->addToRecipient($recipient);
    }

    $batchMessage->finalize();

More info at documentation.