PostPalMail developers
Search /
Help Center API Keys
Guides API Reference
Getting Started
4 min read

PostPalMail API

Authentication

Every request must include your API key as a Bearer token in the Authorization header. Generate a key from your API settings page.

Request
# Every endpoint below requires this header
curl https://postpalmail.com/api/v1/account \
  -H "Authorization: Bearer YOUR_API_KEY"
Requests without a valid key return 401 Unauthorized with an invalid_key or missing_auth error code.

Rate Limits

Each API key is limited to 1,000 requests per day. Once the limit is reached, requests return 401 Unauthorized until the daily window resets.

Contacts

Search and retrieve contacts from your PostPalMail database.

GET /api/v1/contacts

List and filter contacts, paginated.

ParamTypeDescription
countrystringFilter by country
industrystringFilter by industry
keywordstringSearch keyword
statusstringEmail status filter
pageintPage number (default 1)
limitintResults per page, max 200 (default 50)
Request
curl "https://postpalmail.com/api/v1/contacts?country=USA&industry=Technology&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response
{
                        "data": [
    {
                        "id": 4821,
                        "email": "james@techcorp.com",
                        "company": "TechCorp Inc",
                        "country": "USA",
                        "industry": "Technology",
                        "isVerified": true,
                        "phone": null,
                        "website": "techcorp.com",
                        "imported_at": "2026-06-01T10:00:00Z"
    }
  ],
                        "meta": { "page": 1, "limit": 20, "total": 4286, "pages": 215 }
}
GET /api/v1/contacts/{id}

Retrieve a single contact by ID.

Request
curl https://postpalmail.com/api/v1/contacts/4821 \
  -H "Authorization: Bearer YOUR_API_KEY"

Campaigns

Read campaign details and performance stats.

GET /api/v1/campaigns

List your campaigns with send stats, paginated (page, limit — max 100).

Response
{
                        "data": [
    {
                        "id": 102,
                        "name": "Summer Outreach",
                        "subject": "More leads for {{company}}?",
                        "status": "Completed",
                        "stats": {
                        "sent": 2140, "opens": 1463, "clicks": 402,
                        "bounces": 12, "replies": 38, "unsubscribes": 6,
                        "open_rate": 68.4, "click_rate": 18.8
      },
                        "created_at": "2026-06-01T09:00:00Z",
                        "sent_at": "2026-06-02T14:00:00Z"
    }
  ],
                        "meta": { "page": 1, "limit": 20, "total": 14, "pages": 1 }
}
GET /api/v1/campaigns/{id}

Retrieve a single campaign by ID.

Lead Lists

Create and manage saved contact lists.

GET /api/v1/leadlists

List all your lead lists.

POST /api/v1/leadlists

Create a new lead list.

Request
curl -X POST https://postpalmail.com/api/v1/leadlists \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Q3 Prospects", "description": "New leads for Q3"}'
Response
{
                        "id": 55, "name": "Q3 Prospects",
                        "contactCount": 0, "created_at": "2026-08-27T12:00:00Z"
}
GET /api/v1/leadlists/{id}/contacts

List the contacts belonging to a specific lead list.

Email Verification

Check deliverability for a single email or an entire batch.

GET /api/v1/verify?email=someone@example.com

Verify one email address in real time.

Response
{
                        "email": "someone@example.com",
                        "status": "Valid",
                        "risk_score": 12,
                        "checks": {
                        "syntax": true, "disposable": false, "role_based": false,
                        "mx_record": true, "catch_all": false, "smtp": true
  },
                        "checked_at": "2026-08-27T12:05:00Z"
}
POST /api/v1/verify/batch

Queue up to 10,000 emails for background verification.

Request
curl -X POST https://postpalmail.com/api/v1/verify/batch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Import Cleanup", "emails": ["a@x.com", "b@y.com"]}'
Response
{
                        "batch_id": 9, "name": "Import Cleanup",
                        "total": 2, "status": "queued",
                        "check_status_at": "/api/v1/verify/batch/9"
}
GET /api/v1/verify/batch/{id}

Poll a batch job's progress and results.

Sequences

Read your follow-up sequences and enroll contacts programmatically.

GET /api/v1/sequences

List your sequences. GET /api/v1/sequences/{id} returns one sequence's steps.

POST /api/v1/sequences/{id}/enroll

Enroll one or more emails into an existing sequence.

Request
curl -X POST https://postpalmail.com/api/v1/sequences/7/enroll \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emails": ["lead1@company.com", "lead2@company.com"]}'
Response
{ "enrolled": 2, "duplicates": 0, "total_submitted": 2 }

Inbox

GET/api/v1/inbox lists received messages; GET/api/v1/inbox/{id} retrieves one message.

Analytics

GET/api/v1/analytics?days=30 returns totals (sent, opens, clicks, bounces, average rates) and a daily chart series for the given window (1–90 days).

Account

GET/api/v1/account returns your plan, credit balance, monthly usage, and contact/campaign totals.

Blacklist

GET/api/v1/blacklist/{email} checks whether an address is suppressed; POST/api/v1/blacklist adds one manually (body: {"email": "..."}).