Skip to content
Splashify Pro
Email docsEmail

AI Onboarding

Working with an AI coding assistant (Cursor, Claude Code, ChatGPT, Windsurf, etc.)? Paste this page's URL into your assistant — we've formatted everything below for an LLM to ingest in one shot.

For Cursor / Claude Code / Windsurf, run:

text
https://email-docs.splashifypro.com/getting-started/ai-onboarding

You are integrating: Splashify Pro Email API

You are a developer integration assistant. You are helping a user build against the Splashify Pro Email API, a REST API with JSON request and response bodies. Field names are snake_case, responses are flat (success plus the endpoint's fields, no data wrapper), and ids are UUIDs.

Base URL

text
https://api.splashifypro.com/api/v1/partner/email

Authentication

Every request requires a Bearer API key in the Authorization header. Keys are prefixed pk_live_. Generate from email.splashifypro.com → Settings → API key.

text
Authorization: Bearer pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Core concepts

  • Identity: Verified domain or email address. Required before you can send From: that address. Domain identities cover any address at the domain. Verified via DNS records (SPF + DKIM CNAME + DMARC).
  • Configuration Set: A logical grouping of sends. Attach event destinations (webhooks) to a config set; sends specify configuration_set_name to route events.
  • Event Destination: Webhook URL on a config set. Receives the JSON event payload, signed with HMAC-SHA256 when the destination has a webhook_secret.
  • Template: Reusable email body with {{variable}} placeholders. Send via POST /send-template or POST /send-bulk.
  • Suppression list: Account-level. Hard bounces + complaints + unsubscribes auto-add. Sends to suppressed addresses are rejected pre-SMTP.
  • Sandbox: Default state for new accounts. 200/day cap, and every send needs a From on a verified identity. Request production access to lift the cap.
  • Wallet: Prepaid by default. ₹0.03 per email. Sandbox sends are free, up to the 200/day cap. Recharge in Splashify Pro Email.

Most-used endpoints

Send transactional email

bash
POST /api/v1/partner/email/send
{
  "from": "[email protected]",
  "to": ["[email protected]"],
  "subject": "Hello",
  "html_body": "<p>Hi</p>",
  "text_body": "Hi",
  "configuration_set_name": "production",
  "category": "transactional"
}

Response: {"success":true,"results":[{"recipient":"[email protected]","message_id":"<uuid>","status":"queued"}]}

Send templated email

bash
POST /api/v1/partner/email/send-template
{
  "from": "[email protected]",
  "to": ["[email protected]"],
  "template_name": "welcome",
  "variables": {"first_name": "Alex"}
}

Bulk templated send (up to 50 recipients × 50 destinations / 500 total)

bash
POST /api/v1/partner/email/send-bulk
{
  "from": "[email protected]",
  "template_name": "newsletter",
  "default_template_data": {"campaign": "june"},
  "destinations": [
    { "to": ["[email protected]"], "replacement_data": {"first_name": "Alex"} },
    { "to": ["[email protected]"], "replacement_data": {"first_name": "Brett"} }
  ]
}

Get message status

bash
GET /api/v1/partner/email/emails/{message_id}

Verify a sending identity (domain)

bash
POST /api/v1/partner/email/identities
{
  "identity_type": "DOMAIN",
  "identity_value": "yourcompany.com"
}

The response's dns_records lists what to publish (SPF TXT, DKIM CNAME, DMARC TXT, plus dkim2 and return_path when present). After publishing, trigger:

bash
POST /api/v1/partner/email/identities/DOMAIN/yourcompany.com/verify

Create a configuration set

bash
POST /api/v1/partner/email/configuration-sets
{
  "name": "production",
  "suppression_options": "BOUNCE_AND_COMPLAINT"
}

Add a webhook event destination

bash
POST /api/v1/partner/email/configuration-sets/{config_set_id}/event-destinations
{
  "name": "production-webhook",
  "destination_type": "WEBHOOK",
  "webhook_url": "https://yourapp.com/webhooks/splashify",
  "webhook_secret": "your-shared-secret",
  "matching_event_types": ["send", "delivered", "bounce", "complaint", "open", "click"]
}

Suppression list

bash
GET    /api/v1/partner/email/suppression
PUT    /api/v1/partner/email/suppression/{email}
DELETE /api/v1/partner/email/suppression/{email}

Quotas + reputation

bash
GET /api/v1/partner/email/quotas       # daily cap, sandbox, reputation_status
GET /api/v1/partner/email/stats        # day-by-day counters
GET /api/v1/partner/email/reputation   # 14d bounce/complaint rate
GET /api/v1/partner/email/events       # event log

Webhook payload shape

json
{
  "eventType": "Delivery",
  "mail": {
    "timestamp": "2026-05-03T12:34:56Z",
    "messageId": "<uuid>",
    "source": "[email protected]",
    "destination": ["[email protected]"]
  },
  "delivery": {
    "timestamp": "2026-05-03T12:34:57Z",
    "recipients": ["[email protected]"],
    "smtpResponse": "250 OK"
  }
}

Headers:

  • X-Splashify-Event: Send|Delivery|Bounce|Complaint|Open|Click|Reject|DeliveryDelay
  • X-Splashify-Signature: sha256=<hex> HMAC-SHA256 of raw body, key = your webhook_secret. Not sent when the destination has no secret
  • X-Splashify-Timestamp: Unix seconds
  • X-Splashify-Delivery-ID: UUID per delivery attempt, new on every retry

Verify the signature in constant time, dedupe on mail.messageId + eventType, return 200 OK to ack. 4xx = no retry. 5xx + timeout = 3 attempts in all, {1min, 5min} apart.

Sandbox vs production

Sandbox limit: 200 emails / day, all free. Past that, sends stop with 429 until midnight UTC. You can send to any address, and no per-second limit applies to sends.

Request production access:

bash
POST /api/v1/partner/email/production-access
{
  "use_case": "Transactional emails for our SaaS — signup confirms, password resets, payment receipts",
  "email_volume_estimate": "5000-15000 per day",
  "has_unsubscribe_method": true,
  "has_consent_proof": true
}

Approval lifts sandbox + bumps daily cap to 50,000.

Pricing

  • ₹0.03 per email, flat
  • 200/day free in sandbox, then sends stop with 429
  • Custom per-account rates supported (set by our team)

Errors

All errors are {success: false, error: "<CODE>", message: "<human>"} with a 4xx or 5xx status:

  • 400: bad request (read message)
  • 401: invalid / missing API key
  • 402: wallet balance insufficient (recharge)
  • 403: sending paused, key inactive, IP blocked, production access needed
  • 404: not found
  • 429: rate limit (back off), or a daily cap: SANDBOX_QUOTA_REACHED, DAILY_LIMIT_REACHED (don't retry)
  • 503: DB_UNAVAILABLE and RENDERER_UNAVAILABLE (retry), RENDER_FAILED (fix the template)

SDKs

Official SDKs exist for Node.js (@splashifypro/sdk), Python (splashifypro) and PHP (splashifypro/sdk, install with composer require splashifypro/sdk:dev-main). They cover 15 operations: /send, /send-template, /send-bulk, /send-raw, /emails/{message_id}, list + create + verify on /identities, all five /configuration-sets calls, /quotas and /stats. Everything else (templates, suppression, event destinations, events, reputation, production access, audiences) is a plain HTTP call.

Classes and methods are generated from the routes, for example PartnerEmailSendApi.partnerEmailSendPost in Node.js and PHP and partner_email_send_post in Python. Take every name from https://email-docs.splashifypro.com/build-with-ai/sdks and never invent one. Set the host to https://api.splashifypro.com/api/v1 and the auth value to Bearer pk_live_....

Where to read more

That's everything an AI agent needs to start integrating. If your assistant asks about something not covered here, link it to the relevant section above.