Developer REST API and Webhooks

Developer REST API & Webhooks

Integrate PolyPress with your applications using the developer REST API and secure HMAC webhooks.

---

🔑 Authentication

Authenticate API requests by including your API key in the X-PolyPress-Key HTTP header.

X-PolyPress-Key: pp_live_your_api_key_here

---

🛰️ REST API Endpoints

1. Add / Update Subscriber

Add or update contacts in a mailing list:

• Endpoint: POST /api/developer/v1/subscribers
• Headers:
  • X-PolyPress-Key: pp_live_...
  • Content-Type: application/json
• Request Body:

  {
    "list_id": 1,
    "email": "subscriber@domain.com",
    "name": "Jane Doe",
    "custom_data": {
      "city": "Boston",
      "company": "ACME Corp"
    },
    "source_tag": "API Integration"
  }

• Response (200 OK):

  {
    "id": 42,
    "status": "active",
    "detail": "Subscriber added successfully via Developer API."
  }

2. Transactional Direct Send Email

Send transactional emails immediately. This bypasses the outbox queue and delivers the message directly.

• Endpoint: POST /api/developer/v1/send
• Headers:
  • X-PolyPress-Key: pp_live_...
  • Content-Type: application/json
• Request Body:

  {
    "to_email": "recipient@domain.com",
    "subject": "Direct Notification",
    "body_html": "<p>Hello, this is an instant notification sent directly via PolyPress.</p>",
    "smtp_fallback": true
  }

• Response (200 OK):

  {
    "success": true,
    "recipient": "recipient@domain.com",
    "detail": "Sent successfully"
  }

---

⚡ Signed HMAC-SHA256 Webhooks

Configure webhook subscriptions to receive real-time event updates from PolyPress.

Headers

Every webhook payload includes:

• X-PolyPress-Signature: The hex-encoded HMAC-SHA256 signature.
• Content-Type: application/json

Supported Events

• subscriber.subscribe: Triggered when a contact is added to a list.
• subscriber.bounce: Triggered when a delivery bounce is processed.
• email.sent: Triggered when a message is successfully delivered.
• email.deferred: Triggered when a delivery fails temporarily and is retried.

Signature Verification (Node.js/Express)

Verify signatures to ensure webhook payloads are authentic:

const crypto = require('crypto');

app.post('/webhook-receiver', (req, res) => {
    const signature = req.headers['x-polypress-signature'];
    const secret = 'your_webhook_secret';
    
    const computed = crypto
        .createHmac('sha256', secret)
        .update(JSON.stringify(req.body))
        .digest('hex');

    if (signature !== computed) {
        return res.status(401).send('Signature mismatch');
    }
    
    // Payload verified
    console.log('Verified Webhook Event:', req.body.event);
    res.sendStatus(200);
});