Documentation

Postalynk API Documentation

Everything you need to integrate email sending into your application.

Quick Start

1. Get your API key

Create an account and generate an API key from your dashboard. Your API key should be kept secret and never exposed in client-side code.

2. Send your first email

Use the following cURL command to send a test email:

curl -X POST https://api.postalynk.io/v1/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "hello@yourdomain.com",
    "to": ["user@example.com"],
    "subject": "Hello from Postalynk",
    "html": "<h1>Welcome!</h1><p>This is your first email.</p>",
    "text": "Welcome! This is your first email."
  }'

3. Check delivery status

The API returns a messageId that you can use to track delivery status. Check the Messages page in your dashboard or set up webhooks to receive real-time notifications.

Authentication

All API requests must include your API key in the Authorization header:

Authorization: Bearer mf_live_xxxxxxxxxxxxxxxxxxxx

API keys come in two types:

Livemf_live_ - For production use. Emails are actually sent.
Testmf_test_ - For development. Emails are logged but not sent.

Send Email

POST/v1/send

Request Body

Parameter	Type	Required	Description
from	string	Required	Sender email address
to	string[]	Required	Array of recipient email addresses
subject	string	Required	Email subject line
html	string	Optional	HTML email body
text	string	Optional	Plain text email body
cc	string[]	Optional	CC recipients
bcc	string[]	Optional	BCC recipients
replyTo	string	Optional	Reply-to address
templateSlug	string	Optional	Template slug to use
variables	object	Optional	Template variables
tags	string[]	Optional	Tags for filtering
metadata	object	Optional	Custom metadata

Response

{
  "success": true,
  "data": {
    "messageId": "msg_abc123...",
    "status": "queued"
  }
}

Webhooks

Configure webhooks to receive real-time notifications about email events. We'll send a POST request to your endpoint with event data.

Available Events

delivered - Email was delivered to the recipient
opened - Recipient opened the email
clicked - Recipient clicked a link
bounced - Email bounced
failed - Delivery failed
spam - Marked as spam
unsubscribed - Recipient unsubscribed

Payload Format

{
  "event": "delivered",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "messageId": "msg_abc123...",
    "to": "user@example.com",
    "subject": "Welcome!",
    ...
  }
}

Verifying Signatures

Each webhook request includes an X-Postalynk-Signature header. Verify it using your webhook secret:

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Quick Links

Need help?

Can't find what you're looking for? Our team is here to help.

Base URL

https://api.postalynk.io