Developer Documentation

Build an app with your AI

SplashSend writes a brief for the AI tool you build with. Make an app for your own account, or for every SplashSend account.

1. 1Describe itSay what the app should do, and tick what it needs, such as adding people or sending events.
2. 2Build it with your AICopy its brief into your AI tool. The brief says what to build, how to reach SplashSend and how to keep the key safe.
3. 3Switch it onIt starts in test mode, where nothing it does sends an email. When it works, switch it to live.

Two kinds of app

For your account, or for everyone

Everything your AI needs

Docs written for AI tools to read

Start from an example

Briefs for the apps people make most

Each one is a starting point. Make an app from it, and its brief is filled in with your app’s details.

Authentication

All API requests need an API key, sent in the Authorization header as a Bearer token. Create keys under Setup → API keys. When you create a key you choose what it can do: a new key can read and add people and events, and you can tick more, such as orders, products, lists or data sets. A request the key isn’t allowed to make gets a 403.

curl https://splashsend.com/api/v1/contacts \
  -H "Authorization: Bearer sk_live_your_api_key_here"

Connecting a public app

A public app connects to each SplashSend account with OAuth 2.1 and PKCE. The account sees what the app asks for on SplashSend’s allow screen, and the app gets a token that works for that account only. Make the app under Apps, then Apps you’ve made, to get its client ID and secret.

1. 1Send the person to https://splashsend.com/oauth/authorize with response_type=code, your client_id, a redirect_uri you registered, the scope (the permissions it needs, separated by spaces), a state, a code_challenge and code_challenge_method=S256.
2. 2They choose Allow and come back to your redirect_uri with a code and the state. Check that the state is the one you sent.
3. 3Swap the code at https://splashsend.com/api/oauth/token, form-encoded, with grant_type=authorization_code, the code, the redirect_uri and the code_verifier. Send the client ID and secret as HTTP Basic.
4. 4Send the access token with each request as Authorization: Bearer, the same way a key is sent. It lasts an hour. Before then, swap the refresh token for new ones with grant_type=refresh_token. Each refresh token works once.
5. 5A 401 means the account removed your app. Stop calling for that account and ask them to connect again.

curl -X POST https://splashsend.com/api/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code="$CODE" \
  -d redirect_uri=https://yourapp.example/splashsend/callback \
  -d code_verifier="$CODE_VERIFIER"

Base URL

All API endpoints are relative to:

https://splashsend.com/api/v1

People

Create, list, update, and manage your people.

Webhooks

Receive real-time notifications when events happen in your account. Configure webhook endpoints in your dashboard under Setup → Webhooks.

Event types

Payload format

Each webhook POST request includes a JSON body and two special headers:

{
  "id": "evt_Q2xh5M8d0Tq1pZ7kVbN3yR6s",
  "event": "contact.subscribed",
  "timestamp": "2026-10-09T14:30:00.000Z",
  "data": {
    "contactId": "cm4u2x8yq0003l208f1k9d7vz",
    "email": "jane@example.com",
    "name": "Jane Doe"
  }
}

Verifying signatures

To verify a webhook is authentic, compute the HMAC-SHA256 of the raw request body using your webhook secret and compare it to the signature header.

# Save the request body exactly as it arrived, for example as body.json,
# and put your endpoint's signing secret in WEBHOOK_SECRET.
WEBHOOK_SECRET='your_webhook_secret'

# The signature to expect: the hex HMAC-SHA256 of the raw body.
openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" < body.json | awk '{print $NF}'

# It must equal the X-SplashSend-Signature header exactly.

Error handling

All errors return a consistent JSON envelope with an error code and human-readable message.

{
  "error": {
    "code": "validation_error",
    "message": "email is required and must be a string"
  }
}

Rate limiting

Each API key can make 100 requests a minute. A request over the limit gets a 429 with the code rate_limited and a Retry-After header of 60 seconds. Requests refused because the key is missing a scope count towards the limit, and so do an AI assistant's requests made with the same key.