Suggestion: better documentation of `emails` parameter for send_batch and send_template_batch

gregsadetsky commented 2 years ago

The documentation for send_batch and send_template_batch both mention:

Parameters emails – Email instances or dictionaries

However, emails is actually equivalent to *args, i.e. emails internally captures (within send_batch and send_template_batch) all arguments passed to the function. The variable name emails is not actually exposed to the caller, and so isn't properly a "parameter".

Calling:

postmark.emails.send_batch(emails=[email, another_email])

will not work -- the function will instead confusingly return an empty array.

Just in case anybody comes here to troubleshoot this, the correct way to call the functon is rather:

postmark.emails.send_batch(email, another_email)
# ... or alternatively ...
my_emails = [email, another_email]
postmark.emails.send_batch(*my_emails)

Thanks!

digicase commented 2 years ago

Thanks @gregsadetsky that was exactly what I was searching for.

dransome commented 6 months ago

I was passing something like this:

recipients = ["user1@example.com", "user2@example.com"]
subject = "test batch email"
tag = "test-tag"
emails = []
for to in recipients:
    emails.append(
        {
            'To': to,
            'From': 'from@example.com',
            'ReplyTo': 'reply-to@example.com',
            'Subject': subject,
            'Tag': tag,
            'MessageStream': 'broadcast',
            'HtmlBody': html_body,
            'TextBody': text_body,
        }
    )
postmark.emails.send_batch(emails)

Which my read of the docs implies should work?:

postmark.emails.send_batch(
    {
        'From': 'sender@example.com',
        'To': 'receiver@example.com',
        'Subject': 'Postmark test',
        'HtmlBody': '<html><body><strong>Hello</strong> dear Postmark user.</body></html>',
    },
    {
        'From': 'sender2@example.com',
        'To': 'receiver2@example.com',
        'Subject': 'Postmark test 2',
        'HtmlBody': '<html><body><strong>Hello</strong> dear Postmark user.</body></html>',
    }
)

Yet my code was throwing a ValueError; switching to postmark.emails.send_batch(*emails) as per your suggestion @gregsadetsky works fine though - thanks for getting me out of a hole!

Stranger6667 / postmarker

Suggestion: better documentation of `emails` parameter for send_batch and send_template_batch #212