Debugging a Missing Email with Piisend Delivery Logs
Learn how to effectively use Piisend's email delivery logs and webhook events to diagnose why emails aren't reaching their destination. Understand message statuses like queued, sent, delivered, bounced, and failed to quickly troubleshoot delivery issues.
Section 1
Debugging Missing Emails with Piisend Delivery Logs
When an email doesn't arrive as expected, delivery logs are your first line of defense. Piisend provides comprehensive logs that track every email's journey, from initial API call to final delivery status, helping you quickly diagnose issues and ensure reliable communication. These logs are essential for understanding message status and identifying bounced vs failed emails, which are critical for effective support debugging.
Section 2
Decoding Piisend's Email Message Statuses
Piisend categorizes email events into clear statuses. An email can be queued (received by Piisend, awaiting processing), sent (handed off to the recipient's mail server), delivered (accepted by the recipient's mail server), bounced (permanently rejected, e.g., invalid address), or failed (a temporary issue preventing delivery, often retried). Understanding these distinctions is key for effective troubleshooting. For instance, a bounced email indicates a permanent problem, while a failed status might resolve itself on retry.
1curl -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": ["recipient@example.com"],6 "subject": "Your Order Confirmation",7 "html": "<h1>Thank you for your order!</h1><p>Your order #12345 has been confirmed.</p>",8 "text": "Thank you for your order! Your order #12345 has been confirmed."9 }'Section 3
Leveraging Webhook Events for Real-time Debugging
While dashboard logs are great for historical review, Piisend's webhooks provide real-time notifications for critical email events like delivered, bounced, or opened. This allows your application to react instantly, update user interfaces, or trigger further actions. Each webhook event includes a X-Webhook-Signature for verification and X-Webhook-Timestamp to prevent replay attacks, ensuring the integrity and timeliness of your webhook events.
1{2 "event": "delivered",3 "message_id": "msg_1234567890abcdef",4 "recipient": "recipient@example.com",5 "timestamp": 1678886400,6 "payload": {7 "to": ["recipient@example.com"],8 "subject": "Your Order Confirmation",9 "from": "noreply@yourdomain.com"10 }11}Section 4
Advanced Troubleshooting for Persistent Email Problems
If emails are consistently bouncing or failing, check your domain's SPF, DKIM, and DMARC records. Recipient mail servers often reject emails from unverified domains or those flagged for spam. Piisend's email delivery logs will often provide specific error messages from the recipient server, which are invaluable for diagnosing issues like "550 permanent failure for one or more recipients". Using an Idempotency-Key can also help prevent duplicate sends during retry logic, simplifying debugging.
1import requests2import json3 4api_key = "YOUR_API_KEY"5url = "https://api.piisend.com/api/v1/emails"6idempotency_key = "my-unique-send-id-001"7 8headers = {9 "Authorization": f"Bearer {api_key}",10 "Content-Type": "application/json",11 "Idempotency-Key": idempotency_key12}13 14payload = {15 "to": ["user@example.com"],16 "subject": "Password Reset Request",17 "html": "<p>Click <a href=\"https://your-app.com/reset?token=xyz\">here</a> to reset your password.</p>",18 "text": "Reset your password: https://your-app.com/reset?token=xyz"19}20 21try:22 response = requests.post(url, headers=headers, data=json.dumps(payload))23 response.raise_for_status()24 print(f"Email sent successfully: {response.json()}")25except requests.exceptions.RequestException as e:26 print(f"Error sending email: {e}")27 if response is not None:28 print(f"Response body: {response.text}")
