Skip to content
Splashify Pro
Email docsEmail

SDKs

Official SDKs ship for Node.js, Python and PHP. They are generated from our OpenAPI spec, and that spec covers 15 Email API operations: sending, message status, identities, configuration sets, quota and stats. Everything else is a plain HTTP call, shown below.

Don't see your language? The API is plain HTTP and JSON, so every endpoint can be called with the language's standard HTTP client. See the per-language Quickstarts.

Before you start

The SDKs are thin generated clients, so a few things work differently from a hand-written one:

  • Set the host yourself, and stop at /api/v1. Use https://api.splashifypro.com/api/v1. Each SDK method adds /partner/email/... on its own.
  • Include the word Bearer. The SDKs put the auth value in the header as you give it, so the setup below adds the prefix.
  • Bodies are plain objects with the API's own snake_case field names, such as html_body and configuration_set_name. There are no model classes, so the SDK does not check your field names.
  • Responses are the API's JSON as a plain object: success plus the fields of that endpoint, with no data wrapper. Ids are UUIDs.
  • Names come from the route. The classes keep the word Partner from the path, so POST /send is partnerEmailSendPost on PartnerEmailSendApi.

Node.js

bash
npm install @splashifypro/sdk
export SPLASHIFY_API_KEY="pk_live_..."

Save this as send.mjs and run node send.mjs:

javascript
import { Configuration, PartnerEmailSendApi } from "@splashifypro/sdk";

const config = new Configuration({
  basePath: "https://api.splashifypro.com/api/v1",
  apiKey: `Bearer ${process.env.SPLASHIFY_API_KEY}`,
});

const send = new PartnerEmailSendApi(config);

const result = await send.partnerEmailSendPost({
  body: {
    from: "[email protected]",
    to: ["[email protected]"],
    subject: "Welcome",
    html_body: "<h1>Welcome</h1>",
  },
});

console.log(result.results[0].message_id);

More calls, using the same config, send and result:

javascript
import {
  PartnerEmailConfigurationSetsApi,
  PartnerEmailIdentitiesApi,
  PartnerEmailStatsApi,
} from "@splashifypro/sdk";

// Add a domain, publish its DNS records, then check them
const identities = new PartnerEmailIdentitiesApi(config);
const created = await identities.partnerEmailIdentitiesPost({
  body: { identity_type: "DOMAIN", identity_value: "yourcompany.com" },
});
console.log(created.dns_records);

const check = await identities.partnerEmailIdentitiesTypeValueVerifyPost({
  type: "DOMAIN",
  value: "yourcompany.com",
});
console.log(check.status);

// Create a configuration set. Send through it with configuration_set_name
const configSets = new PartnerEmailConfigurationSetsApi(config);
const { configuration_set } = await configSets.partnerEmailConfigurationSetsPost({
  body: { name: "production" },
});
console.log(configuration_set.config_set_id);

// Status of one message
const message = await send.partnerEmailEmailsMessageIdGet({
  messageId: result.results[0].message_id,
});
console.log(message.status);

// Quota and day-by-day stats
const reports = new PartnerEmailStatsApi(config);
const { quota } = await reports.partnerEmailQuotasGet();
const { stats } = await reports.partnerEmailStatsGet({ days: 14 });
console.log(quota.sent_today, stats.length);

A 4xx or 5xx throws ResponseError. The API's JSON is on err.response:

javascript
import { ResponseError } from "@splashifypro/sdk";

try {
  await send.partnerEmailSendPost({
    body: {
      from: "[email protected]",
      to: ["[email protected]"],
      subject: "Welcome",
      text_body: "Welcome.",
    },
  });
} catch (err) {
  if (!(err instanceof ResponseError)) throw err;
  const body = await err.response.json();
  console.error(err.response.status, body.message);
}

TypeScript types ship with the package. Bodies are typed as object and responses as a plain map, so they do not check field names.

Python

bash
pip install splashifypro
export SPLASHIFY_API_KEY="pk_live_..."
python
import os
import splashifypro

config = splashifypro.Configuration(
    host="https://api.splashifypro.com/api/v1",
    api_key={"BearerAuth": os.environ["SPLASHIFY_API_KEY"]},
    api_key_prefix={"BearerAuth": "Bearer"},
)

with splashifypro.ApiClient(config) as client:
    send = splashifypro.PartnerEmailSendApi(client)

    result = send.partner_email_send_post(body={
        "from": "[email protected]",
        "to": ["[email protected]"],
        "subject": "Welcome",
        "html_body": "<h1>Welcome</h1>",
    })
    print(result["results"][0]["message_id"])

More calls, using the same config:

python
import json

with splashifypro.ApiClient(config) as client:
    send = splashifypro.PartnerEmailSendApi(client)
    identities = splashifypro.PartnerEmailIdentitiesApi(client)
    config_sets = splashifypro.PartnerEmailConfigurationSetsApi(client)
    reports = splashifypro.PartnerEmailStatsApi(client)

    # Add a domain. A new identity answers 201, and this method only
    # returns a value for 200, so read the raw body.
    response = identities.partner_email_identities_post_with_http_info(body={
        "identity_type": "DOMAIN",
        "identity_value": "yourcompany.com",
    })
    print(json.loads(response.raw_data)["dns_records"])

    # After you publish the DNS records, check them
    check = identities.partner_email_identities_type_value_verify_post(
        type="DOMAIN",
        value="yourcompany.com",
    )
    print(check["status"])

    # Create a configuration set. Send through it with configuration_set_name
    created = config_sets.partner_email_configuration_sets_post(
        body={"name": "production"},
    )
    print(created["configuration_set"]["config_set_id"])

    # Status of one message
    message = send.partner_email_emails_message_id_get(
        message_id="550e8400-e29b-41d4-a716-446655440000",
    )
    print(message["status"])

    # Quota and day-by-day stats
    quota = reports.partner_email_quotas_get()
    stats = reports.partner_email_stats_get(days=14)
    print(quota["quota"]["sent_today"], len(stats["stats"]))

A 4xx or 5xx raises splashifypro.ApiException. The API's JSON is in e.body:

python
import json

with splashifypro.ApiClient(config) as client:
    send = splashifypro.PartnerEmailSendApi(client)
    try:
        send.partner_email_send_post(body={
            "from": "[email protected]",
            "to": ["[email protected]"],
            "subject": "Welcome",
            "text_body": "Welcome.",
        })
    except splashifypro.ApiException as e:
        print(e.status, json.loads(e.body).get("message"))

The SDK is synchronous. In async code, run a call in a thread:

python
import asyncio

async def main():
    with splashifypro.ApiClient(config) as client:
        send = splashifypro.PartnerEmailSendApi(client)
        result = await asyncio.to_thread(
            send.partner_email_send_post,
            body={
                "from": "[email protected]",
                "to": ["[email protected]"],
                "subject": "Welcome",
                "text_body": "Welcome.",
            },
        )
        print(result["results"][0]["message_id"])

asyncio.run(main())

PHP

The package has no tagged release yet, so name the dev-main branch when you install it. A plain composer require splashifypro/sdk stops with a stability error.

bash
composer require splashifypro/sdk:dev-main
export SPLASHIFY_API_KEY="pk_live_..."
php
<?php
require __DIR__ . '/vendor/autoload.php';

use GuzzleHttp\Client;
use Splashifypro\Api\PartnerEmailSendApi;
use Splashifypro\Configuration;

$config = (new Configuration())
    ->setHost('https://api.splashifypro.com/api/v1')
    ->setApiKey('Authorization', getenv('SPLASHIFY_API_KEY'))
    ->setApiKeyPrefix('Authorization', 'Bearer');

$send = new PartnerEmailSendApi(new Client(), $config);

$result = $send->partnerEmailSendPost([
    'from'      => '[email protected]',
    'to'        => ['[email protected]'],
    'subject'   => 'Welcome',
    'html_body' => '<h1>Welcome</h1>',
]);

echo $result['results'][0]->message_id;

The response is an array at the top level, and anything nested in it is a stdClass object. That is why the last line uses ->message_id.

More calls, using the same $config, $send and $result:

php
use Splashifypro\Api\PartnerEmailConfigurationSetsApi;
use Splashifypro\Api\PartnerEmailIdentitiesApi;
use Splashifypro\Api\PartnerEmailStatsApi;

// Add a domain, publish its DNS records, then check them
$identities = new PartnerEmailIdentitiesApi(new Client(), $config);
$created = $identities->partnerEmailIdentitiesPost([
    'identity_type'  => 'DOMAIN',
    'identity_value' => 'yourcompany.com',
]);
print_r($created['dns_records']);

$check = $identities->partnerEmailIdentitiesTypeValueVerifyPost('DOMAIN', 'yourcompany.com');
echo $check['status'];

// Create a configuration set. Send through it with configuration_set_name
$configSets = new PartnerEmailConfigurationSetsApi(new Client(), $config);
$set = $configSets->partnerEmailConfigurationSetsPost(['name' => 'production']);
echo $set['configuration_set']->config_set_id;

// Status of one message
$message = $send->partnerEmailEmailsMessageIdGet($result['results'][0]->message_id);
echo $message['status'];

// Quota and day-by-day stats
$reports = new PartnerEmailStatsApi(new Client(), $config);
$quota = $reports->partnerEmailQuotasGet();
$stats = $reports->partnerEmailStatsGet(14);
echo $quota['quota']->sent_today, ' ', count($stats['stats']);

A 4xx or 5xx throws Splashifypro\ApiException. The API's JSON is in getResponseBody():

php
use Splashifypro\ApiException;

try {
    $send->partnerEmailSendPost([
        'from'      => '[email protected]',
        'to'        => ['[email protected]'],
        'subject'   => 'Welcome',
        'text_body' => 'Welcome.',
    ]);
} catch (ApiException $e) {
    $body = json_decode($e->getResponseBody(), true);
    echo $e->getCode(), ' ', $body['message'] ?? $e->getMessage();
}

Operations the SDKs cover

These 15 calls are in all three SDKs. Paths are relative to the base URL.

How arguments are passed:

The SDKs have no limit or cursor argument yet, so GET /identities and GET /configuration-sets read only the first 100 rows. To read the rest, call those routes over plain HTTP, see Pagination.

The verify method sends no body, so use it for DOMAIN identities. For an EMAIL_ADDRESS identity, follow Verify identity over plain HTTP.

Operations not in the SDKs

These calls have no SDK method. Call them over plain HTTP with the same key, against https://api.splashifypro.com/api/v1/partner/email.

cURL:

bash
export API="https://api.splashifypro.com/api/v1/partner/email"

# Save a template
curl "$API/templates" \
  -H "Authorization: Bearer $SPLASHIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_name": "welcome",
    "subject": "Welcome, {{first_name}}",
    "html": "<h1>Hi {{first_name}}</h1>"
  }'

# Add an address to the suppression list
curl -X PUT "$API/suppression/[email protected]" \
  -H "Authorization: Bearer $SPLASHIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason": "MANUAL"}'

# Read today's events
curl "$API/events?limit=50" \
  -H "Authorization: Bearer $SPLASHIFY_API_KEY"

Node.js, with the fetch built into Node 18+:

javascript
const API = "https://api.splashifypro.com/api/v1/partner/email";

async function api(method, path, body) {
  const res = await fetch(API + path, {
    method,
    headers: {
      Authorization: `Bearer ${process.env.SPLASHIFY_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: body === undefined ? undefined : JSON.stringify(body),
  });
  const data = await res.json();
  if (!res.ok) throw new Error(`${res.status}: ${data.message}`);
  return data;
}

// Save a template. partnerEmailSendTemplatePost sends it by template_name
const { template } = await api("POST", "/templates", {
  template_name: "welcome",
  subject: "Welcome, {{first_name}}",
  html: "<h1>Hi {{first_name}}</h1>",
});
console.log(template.template_id);

// Add an address to the suppression list
await api("PUT", "/suppression/[email protected]", { reason: "MANUAL" });

// Add a webhook to a configuration set. The id is its config_set_id
const configSetId = "550e8400-e29b-41d4-a716-446655440000";
await api("POST", `/configuration-sets/${configSetId}/event-destinations`, {
  name: "production-webhook",
  webhook_url: "https://yourapp.com/webhooks/splashify",
  webhook_secret: "your-shared-secret",
  matching_event_types: ["delivered", "bounce", "complaint"],
});

// Read today's events
const { events } = await api("GET", "/events?limit=50");
console.log(events.length);

Python, with requests:

python
import os
import requests

API = "https://api.splashifypro.com/api/v1/partner/email"
HEADERS = {"Authorization": f"Bearer {os.environ['SPLASHIFY_API_KEY']}"}

# Save a template. partner_email_send_template_post sends it by template_name
r = requests.post(f"{API}/templates", headers=HEADERS, json={
    "template_name": "welcome",
    "subject": "Welcome, {{first_name}}",
    "html": "<h1>Hi {{first_name}}</h1>",
})
r.raise_for_status()
print(r.json()["template"]["template_id"])

# Add an address to the suppression list
r = requests.put(
    f"{API}/suppression/[email protected]",
    headers=HEADERS,
    json={"reason": "MANUAL"},
)
r.raise_for_status()

# Read today's events
r = requests.get(f"{API}/events", headers=HEADERS, params={"limit": 50})
r.raise_for_status()
print(len(r.json()["events"]))

PHP, with Guzzle, which the SDK already installs:

php
<?php
require __DIR__ . '/vendor/autoload.php';

$http = new GuzzleHttp\Client([
    'base_uri' => 'https://api.splashifypro.com/api/v1/partner/email/',
    'headers'  => ['Authorization' => 'Bearer ' . getenv('SPLASHIFY_API_KEY')],
]);

// Save a template. partnerEmailSendTemplatePost sends it by template_name
$res = $http->post('templates', ['json' => [
    'template_name' => 'welcome',
    'subject'       => 'Welcome, {{first_name}}',
    'html'          => '<h1>Hi {{first_name}}</h1>',
]]);
$saved = json_decode((string) $res->getBody(), true);
echo $saved['template']['template_id'];

// Add an address to the suppression list
$http->put('suppression/[email protected]', ['json' => ['reason' => 'MANUAL']]);

// Read today's events
$res = $http->get('events', ['query' => ['limit' => 50]]);
$data = json_decode((string) $res->getBody(), true);
echo count($data['events']);

Versioning

The Node.js and Python packages are at version 0.1.0. PHP has no tagged release yet, so commit your composer.lock to stay on a known commit. The API itself is versioned under /api/v1/, and we'll ship /api/v2/ before any breaking contract change.

Reporting issues

Each SDK has its own repo that accepts issues. The code is generated, so fixes come from our side rather than from pull requests:

For platform-side bugs (the API misbehaving regardless of SDK), or for anything you can't reduce to a single language, email [email protected] with the request payload + the pk_live_ key prefix (first 12 chars).