Scheduling and Canceling Transactional Emails with Piisend
Learn how to leverage Piisend's schedule email API to send delayed transactional emails. This guide covers using the scheduled_at field and canceling scheduled messages before dispatch.
Section 1
The Power of Scheduled Transactional Emails
Transactional emails are critical for user engagement, but sometimes immediate delivery isn't ideal. With Piisend's schedule email API, you can easily implement delayed transactional email sends, enhancing user experience for scenarios like welcome sequences, follow-up reminders, or post-purchase surveys. This flexibility allows you to time your communications perfectly.
Section 2
Scheduling an Email with Piisend's API
To schedule an email, simply include the "scheduled_at" field in your POST request to the Piisend emails endpoint. The value for "scheduled_at" must be an ISO-8601 formatted timestamp in UTC, indicating when you want the email to be dispatched. Piisend will hold the email until this time, then process it for delivery.
1curl -X POST https://api.piisend.com/api/v1/emails \2 -H "Authorization: Bearer YOUR_API_KEY" \3 -H "Content-Type: application/json" \4 -H "Idempotency-Key: order-confirmation-12345-scheduled" \5 -d '{6 "to": ["recipient@example.com"],7 "subject": "Your Order Confirmation (Delayed)",8 "html": "<h1>Thank you for your purchase!</h1><p>Your order will be processed shortly.</p>",9 "text": "Thank you for your purchase! Your order will be processed shortly.",10 "scheduled_at": "2026-12-31T10:00:00Z"11 }'Section 3
Managing Scheduled Emails: Status and Cancellation
Once an email is successfully scheduled, its status will be "scheduled". Piisend provides the ability to cancel scheduled email sends before their dispatch time. This is particularly useful if an event changes, such as a user canceling an order or updating their preferences. To cancel, you'll need the email's unique ID returned from the initial send request.
1const fetch = require('node-fetch');2 3async function cancelScheduledEmail(emailId, apiKey) {4 const response = await fetch(`https://api.piisend.com/api/v1/emails/${emailId}/cancel`, {5 method: 'POST',6 headers: {7 'Authorization': `Bearer ${apiKey}`,8 'Content-Type': 'application/json'9 }10 });11 12 if (response.ok) {13 console.log(`Email ${emailId} successfully canceled.`);14 const data = await response.json();15 console.log(data);16 } else {17 console.error(`Failed to cancel email ${emailId}: ${response.status} ${response.statusText}`);18 const errorData = await response.json();19 console.error(errorData);20 }21}22 23// Example usage:24// Replace with your actual email ID and API key25// cancelScheduledEmail('email_id_from_previous_send', 'YOUR_API_KEY');Section 4
Important Considerations for Delayed Sends
When working with scheduled emails, always ensure your "scheduled_at" timestamps are in UTC to avoid timezone-related issues. Also, remember that Piisend's Idempotency-Key header is crucial for preventing duplicate sends, even for scheduled messages. If a network error occurs during the initial scheduling request, retrying with the same Idempotency-Key ensures only one email is scheduled. Monitor webhook delivery events to confirm successful dispatch or cancellation.
