Use Postmark's new bulk-email API for batch sends?

[medmunds]

Postmark has added a new bulk API that can often be used in place of the batch API, and may result in smaller payloads: https://postmarkapp.com/bulk-api

Investigate whether this would be helpful in django-anymail's Postmark backend. (Enabling the API currently requires contacting support, so it may not be a good option just yet.)

API docs: https://postmarkapp.com/developer/api/bulk-email

[interDist]

Would love to use the bulk API via Anymail! Maybe it could be a Postmark-specific opt-in flag?

[marty0678]

Would also be very interested in this too! I think making it a specific opt-in flag makes sense. I don't know what happens if you try to hit the endpoint when your account doesn't have this enabled, but perhaps it could fallback to the older /batch endpoint if the /bulk endpoint returns something clear.

[medmunds]

I've requested access to the API for Anymail's testing account.

Looks like the response when not enabled is HTTP 422:

{
  "ErrorCode": 14,
  "Message": "This endpoint requires approval to access. Contact support to use the Bulk API postmarkapp.com/contact"
}

That said, I think we'd probably make it opt-in via a setting. (I'd like to avoid extra API calls and expected errors in normal use.)

Or maybe it should be a separate email backend? (Like anymail.backends.postmark_bulk.EmailBackend.) I think the bulk API handles single messages and non-templated sends just fine, so using it for all sending would be a much simpler approach compared to the logic in the current Postmark backend.

[medmunds]

OK, I have access to Postmark's bulk API and have started experimenting with it. (They enabled it within a few hours of my request; I'm just getting around to writing this up now.)

Unfortunately, bulk send will need to be opt-in via a setting. Anymail can't switch to the bulk API for all sends. Like Postmark's four other sending APIs, the bulk API's new capabilities come with a few unique quirks and limitations:

• The bulk API only works with a broadcast message stream. Trying to use it with a transactional stream causes a 422 error.
• The bulk API does not return any MessageIds to correlate tracking webhook events with the sent messages. I still need to experiment to see if the bulk "request ID" appears anywhere in webhook payloads. If not, Anymail will probably synthesize a metadata message_id for each recipient like we do for some other ESPs.
• The bulk API does support on-the-fly templates defined in the message subject and html/text bodies. (Still need to test other headers like From or Reply-To.) This seems unique to the bulk API right now; Postmark's other batch sending APIs require ESP-stored templates for this (see Postmark merge_data ignored without template_id #470).

I'm leaning toward a new ANYMAIL setting POSTMARK_USE_BULK_API: True, which would tell Anymail to use the bulk API for all sends. For now, the specific MessageStream could be set as documented in esp_extra.

We might also allow overriding use_bulk_api for individual messages in esp_extra, but I want to think about that a little: Django 6.1 introduces a MAILERS dict setting for defining multiple email configurations, and it would be cleaner (and less code) to configure use_bulk_api and message_stream through that rather than individual message overrides.