Passing Custom Headers on Piisend for Transactional Email Metadata
Learn how to leverage custom email headers, also known as X-headers, with Piisend's transactional email API. These headers are crucial for adding custom metadata to your emails, aiding in internal tracking, support ticket correlation, and enhancing your email workflows.
Section 1
Understanding Custom Email Headers (X-Headers)
Custom email headers, often prefixed with X-, allow developers to embed additional, non-standard information within an email's metadata. While not visible to the end-user in most email clients, these X-headers are invaluable for internal systems. They can carry transactional email metadata that helps in categorizing, tracking, or correlating emails with specific actions or records in your application, making them a powerful feature of any robust email API for developers.
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": "<p>Thank you for your order!</p>"8 }'Section 2
Adding Custom Headers to Your Piisend Emails
Piisend's email API makes it straightforward to include custom headers in your transactional emails. You simply add a headers object to your API request payload, where each key-value pair represents a custom header name and its corresponding value. It's best practice to prefix your custom headers with X- to prevent conflicts with standard email headers. This allows you to attach specific transactional email metadata directly to the message.
1const fetch = require('node-fetch');2 3async function sendEmailWithCustomHeaders() {4 const response = await fetch('https://api.piisend.com/api/v1/emails', {5 method: 'POST',6 headers: {7 'Authorization': 'Bearer YOUR_API_KEY',8 'Content-Type': 'application/json'9 },10 body: JSON.stringify({11 to: ['user@example.com'],12 subject: 'Password Reset Request',13 html: '<p>Click here to reset your password.</p>',14 headers: {15 'X-User-ID': 'user_12345',16 'X-Request-ID': 'req_abcde'17 }18 })19 });20 21 const data = await response.json();22 console.log(data);23}24 25sendEmailWithCustomHeaders();Section 3
Practical Applications of Custom X-Headers
Custom X-headers are incredibly useful for various operational and analytical purposes. For instance, you can use them to link an email to a specific customer ID in your CRM, a support ticket number, or an internal tracking ID for a particular transaction. This transactional email metadata can significantly streamline debugging, customer support, and internal reporting by providing immediate context for each email sent through the email API. They can also help in threading related emails together in some systems.
1import requests2import json3 4def send_email_with_custom_headers():5 api_key = "YOUR_API_KEY"6 url = "https://api.piisend.com/api/v1/emails"7 headers = {8 "Authorization": f"Bearer {api_key}",9 "Content-Type": "application/json"10 }11 payload = {12 "to": ["customer@example.com"],13 "subject": "Your Recent Purchase Details",14 "html": "<p>Thank you for your purchase! Details attached.</p>",15 "headers": {16 "X-Order-ID": "ORD-2023-001",17 "X-Customer-Segment": "VIP"18 }19 }20 21 response = requests.post(url, headers=headers, data=json.dumps(payload))22 print(response.status_code)23 print(response.json())24 25send_email_with_custom_headers()Section 4
Header Behavior and Deliverability Considerations
While Piisend reliably transmits the custom email headers you provide, it's important to understand that the ultimate behavior of these headers can vary. Receiving email servers and clients might strip or ignore non-standard headers, especially if they don't conform to certain conventions. However, X-headers are generally well-preserved for internal use. Piisend ensures that your specified email API headers are included in the message before it leaves our system, giving you control over your transactional email metadata for internal processing.
