Tutorial•3 min read

Seamlessly Migrate Your Transactional Emails from SendGrid to Piisend

Migrating your transactional email API from SendGrid to Piisend offers a streamlined developer experience and robust deliverability. This guide provides a step-by-step walkthrough for a smooth transition, ensuring your emails continue to reach inboxes reliably.

Seamlessly Migrate Your Transactional Emails from SendGrid to Piisend

Section 1

Why Migrate from SendGrid to Piisend?

Developers often seek alternatives to established email APIs like SendGrid for various reasons, including cost, feature set, or a desire for a more modern, developer-centric platform. Piisend is designed to be a powerful SendGrid alternative, offering a straightforward REST API, comprehensive delivery logs, and advanced webhook capabilities. Our focus on deliverability and a clean API makes the Piisend integration process efficient and rewarding for any developer looking to migrate email API services.

Section 2

Setting Up Your Piisend Account and API Key

Before you can start sending emails, you'll need to create a Piisend account and generate an API key. This key will authenticate your requests to the Piisend API. Once logged in, navigate to your API Keys section to create a new key. Remember to keep your API key secure and never expose it in client-side code. After obtaining your key, you can verify your domain to ensure optimal deliverability by setting up SPF, DKIM, and DMARC records.

bash
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 First Piisend Email",
7    "html": "<p>Hello from Piisend! This is your first test email.</p>",
8    "text": "Hello from Piisend! This is your first test email."
9  }'

Section 3

Migrating Basic Email Sending from SendGrid

SendGrid's API typically uses /mail/send for sending emails, often with a complex JSON payload. Piisend simplifies this with a clean POST https://api.piisend.com/api/v1/emails endpoint. You'll map your to, subject, html, and text fields directly. The example below demonstrates how to send a basic transactional email using Piisend's API, which is a common pattern for transactional email API switch scenarios.

python
1import requests
2 
3PIISEND_API_KEY = "YOUR_API_KEY"
4PIISEND_API_URL = "https://api.piisend.com/api/v1/emails"
5 
6headers = {
7    "Authorization": f"Bearer {PIISEND_API_KEY}",
8    "Content-Type": "application/json"
9}
10 
11payload = {
12    "to": ["user@example.com"],
13    "subject": "Order Confirmation: Your Piisend Purchase",
14    "html": "<strong>Thank you for your order!</strong> Your items will ship soon.",
15    "text": "Thank you for your order! Your items will ship soon."
16}
17 
18response = requests.post(PIISEND_API_URL, headers=headers, json=payload)
19 
20if response.status_code == 200:
21    print("Email sent successfully!")
22else:
23    print(f"Failed to send email: {response.status_code} - {response.text}")

Section 4

Migrating Email Templates and Dynamic Content

SendGrid uses dynamic templates with Handlebars-like syntax. Piisend also supports email templates with merge variables, allowing you to send personalized content efficiently. First, create your template in the Piisend dashboard, noting its template_id. Then, pass your dynamic data as template_vars in your API request. This approach is ideal for common transactional emails like OTP verification, password resets, or order confirmations.

javascript
1async function sendTemplatedEmail() {
2  const PIISEND_API_KEY = "YOUR_API_KEY";
3  const PIISEND_API_URL = "https://api.piisend.com/api/v1/emails";
4 
5  const headers = {
6    "Authorization": `Bearer ${PIISEND_API_KEY}`,
7    "Content-Type": "application/json"
8  };
9 
10  const payload = {
11    "to": ["customer@example.com"],
12    "template_id": "tpl_your_template_id",
13    "template_vars": {
14      "customer_name": "Alice",
15      "order_number": "#12345",
16      "product_list": [
17        { "name": "Product A", "quantity": 1 },
18        { "name": "Product B", "quantity": 2 }
19      ]
20    }
21  };
22 
23  try {
24    const response = await fetch(PIISEND_API_URL, {
25      method: "POST",
26      headers: headers,
27      body: JSON.stringify(payload)
28    });
29 
30    if (response.ok) {
31      console.log("Templated email sent successfully!");
32    } else {
33      const errorData = await response.json();
34      console.error(`Failed to send email: ${response.status} - ${JSON.stringify(errorData)}`);
35    }
36  } catch (error) {
37    console.error("Network error:", error);
38  }
39}
40 
41sendTemplatedEmail();

Section 5

Handling Webhooks for Delivery Events

SendGrid provides webhooks for delivery events like bounces, opens, and clicks. Piisend offers similar functionality, allowing you to track the lifecycle of your emails in real-time. Configure your webhook endpoint in the Piisend dashboard. When an event occurs, Piisend will send a POST request to your URL. For security, always verify the webhook signature using the X-Webhook-Signature header (HMAC-SHA256 of the raw body) and X-Webhook-Timestamp to prevent replay attacks. This ensures the integrity and authenticity of incoming events.

http
1POST /your-webhook-endpoint HTTP/1.1
2Host: your-app.com
3Content-Type: application/json
4X-Webhook-Signature: sha256=YOUR_HMAC_SHA256_SIGNATURE
5X-Webhook-Timestamp: 1678886400
6 
7{
8  "event": "delivered",
9  "email_id": "email_abc123",
10  "recipient": "user@example.com",
11  "timestamp": 1678886400,
12  "details": {
13    "message_id": "<abc@piisend.com>",
14    "reason": ""
15  }
16}

More from the blog

All posts

Start sending

Ship transactional email in minutes

Create an API key, verify a domain, and send your first message with Piisend.

QuickstartGet started free