Sending Batch Transactional Emails with Piisend API
Learn how to efficiently send bulk transactional emails using Piisend's REST API. Discover when to batch, how to structure your payload, and handle recipient-specific data for optimized delivery.
Section 1
When to Use Batch Transactional Emails
Batch transactional emails are ideal when you need to send similar, personalized messages to a large recipient list efficiently. Unlike marketing blasts, these are still event-triggered and critical, such as weekly reports, system notifications, or digests. Leveraging a batch email approach through a robust REST API like Piisend helps you manage your rate limits and reduce API call overhead, making your application more performant and scalable for bulk transactional needs.
Section 2
Crafting Your Piisend Batch Payload
Piisend's API allows you to send emails to multiple recipients in a single POST request to the /v1/emails endpoint. This is achieved by providing an array of recipient objects, each with its own 'to' address and optional merge variables. This method is perfect for sending the same email template with slight variations to a large recipient list without making individual API calls for each one.
1curl -sS -X POST https://api.piisend.com/api/v1/emails \2 -H "Authorization: Bearer YOUR_API_KEY" \3 -H "Content-Type: application/json" \4 -d '{5 "to": ["alice@example.com"],6 "template_id": "YOUR_TEMPLATE_OBJECT_ID",7 "template_vars": {8 "name": "Alice"9 }10 }'Section 3
Dynamic Content for Each Recipient
For true transactional email API power, you'll often need to send highly personalized content within your batch emails. Piisend supports merge variables that allow you to inject unique data for each recipient. This means you can send a single batch request, but each user receives an email tailored to their specific information, such as account details, recent activity, or custom messages. This approach significantly streamlines sending personalized bulk transactional emails.
1import os2import httpx3 4recipients = [5 {"to": "charlie@example.com", "name": "Charlie", "report_link": "https://example.com/reports/charlie"},6 {"to": "diana@example.com", "name": "Diana", "report_link": "https://example.com/reports/diana"},7]8 9for recipient in recipients:10 response = httpx.post(11 "https://api.piisend.com/api/v1/emails",12 headers={"Authorization": f"Bearer {os.environ['PIISEND_API_KEY']}"},13 json={14 "to": [recipient["to"]],15 "template_id": "YOUR_TEMPLATE_OBJECT_ID",16 "template_vars": {17 "name": recipient["name"],18 "report_link": recipient["report_link"],19 },20 },21 timeout=30.0,22 )23 response.raise_for_status()24 print(recipient["to"], response.json()["id"])Section 4
Handling Batch Send Responses and Errors
When sending batch emails, the Piisend API provides a comprehensive response indicating the overall status of the request. It's crucial to parse this response to understand which emails were successfully queued and if any encountered recipient-specific issues. While Piisend's infrastructure is designed for high deliverability, understanding the API's feedback helps you implement robust error handling. For very large recipient lists, be mindful of API rate limits and consider breaking down your batches or implementing retry logic with exponential backoff.
