sendpost-js-sdk

v3.0.0

Published

12 days ago

# Introduction > ### 📌 API versioning & the v1 response contract > > This reference documents the **v1 response contract** — the stable, camelCase > response shape that SendPost commits to. This is the shape you should build against. > > **During the cu

0High
0Medium
0Low

sendpost

sendpost-js-sdk

sendpost - JavaScript client for sendpost-js-sdk

Introduction

📌 API versioning & the v1 response contract
This reference documents the v1 response contract — the stable, camelCase response shape that SendPost commits to. This is the shape you should build against.
During the current deprecation window, requests authenticated with an account or sub-account API key receive the legacy response shape by default, so existing integrations keep working unchanged. To receive the documented v1 shape today, send:
X-SendPost-Public-Contract: v1
How to tell which shape you got. Every public response echoes the applied contract in the X-SendPost-Public-Contract response header. While the legacy shape is being served, responses also carry standard deprecation signals: Deprecation: true, a Sunset header with the exact cut-over date, and a Link: <...>; rel=\"deprecation\" header pointing at the migration guide. Read the Sunset header for the authoritative end date rather than hardcoding one.
After the sunset date, v1 becomes the default and the legacy shape is no longer served. New integrations should send X-SendPost-Public-Contract: v1 now and rely on the shapes in this reference.

SendPost provides email API and SMTP relay which can be used not just to send & measure but also alert & optimised email sending.

You can use SendPost to:

Send personalised emails to multiple recipients using email API
Track opens and clicks
Analyse statistics around open, clicks, bounce, unsubscribe and spam

At and advanced level you can use it to:

Manage multiple sub-accounts which may map to your promotional or transactional sending, multiple product lines or multiple customers
Classify your emails using groups for better analysis
Analyse and fix email sending at sub-account level, IP Pool level or group level
Have automated alerts to notify disruptions regarding email sending
Manage different dedicated IP Pools so to better control your email sending
Automatically know when IP or domain is blacklisted or sender score is down
Leverage pro deliverability tools to get significantly better email deliverability & inboxing

Overview

REST API

SendPost API is built on REST API principles. Authenticated users can interact with any of the API endpoints to perform:

GET- to get a resource
POST - to create a resource
PUT - to update an existing resource
DELETE - to delete a resource

The API endpoint for all API calls is: https://api.sendpost.io/api/v1

Some conventions that have been followed in the API design overall are following:

All resources have either /api/v1/subaccount or /api/v1/account in their API call resource path based on who is authorised for the resource. All API calls with path /api/v1/subaccount use X-SubAccount-ApiKey in their request header. Likewise all API calls with path /api/v1/account use X-Account-ApiKey in their request header.
All resource endpoints end with singular name and not plural. So we have domain instead of domains for domain resource endpoint. Likewise we have sender instead of senders for sender resource endpoint.
Body submitted for POST / PUT API calls as well as JSON response from SendPost API follow camelcase convention
All timestamps returned in response (created or submittedAt response fields) are UNIX nano epoch timestamp.

SendPost uses conventional HTTP response codes to indicate the success or failure of an API request.

Codes in the 2xx range indicate success.
Codes in the 4xx range indicate an error owing due to unauthorize access, incorrect request parameters or body etc.
Code in the 5xx range indicate an eror with SendPost's servers ( internal service issue or maintenance )

Authentication

SendPost uses API keys for authentication. You can register a new SendPost API key at our developer portal.

SendPost expects the API key to be included in all API requests to the server in a header that looks like the following:

X-SubAccount-ApiKey: AHEZEP8192SEGH

This API key is used for all Sub-Account level operations such as:

Sending emails
Retrieving stats regarding open, click, bounce, unsubscribe and spam
Uploading suppressions list
Verifying sending domains and more

In addition to X-SubAccount-ApiKey you also have another API Key X-Account-APIKey which is used for Account level operations such as :

Creating and managing sub-accounts
Allocating IPs for your account
Getting overall billing and usage information
Email List validation
Creating and managing alerts and more

In case an incorrect API Key header is specified or if it is missed you will get HTTP Response 401 ( Unauthorized ) response from SendPost.

HTTP Response Headers

Code | Reason | Details ---------------| -----------------------| ----------- 200 | Success | Everything went well 401 | Unauthorized | Incorrect or missing API header either X-SubAccount-ApiKey or X-Account-ApiKey 403 | Forbidden | Typically sent when resource with same name or details already exist 406 | Missing resource id | Resource id specified is either missing or doesn't exist 422 | Unprocessable entity | Request body is not in proper format 500 | Internal server error | Some error happened at SendPost while processing API request 503 | Service Unavailable | SendPost is offline for maintenance. Please try again later

API SDKs

We have native SendPost SDKs in the following programming languages. You can integrate with them or create your own SDK with our API specification. In case you need any assistance with respect to API then do reachout to our team from website chat or email us at [email protected]

API Reference

SendX REST API can be broken down into two major sub-sections:

Sub-Account
Account

Sub-Account API operations enable common email sending API use-cases like sending bulk email, adding new domains or senders for email sending programmatically, retrieving stats, adding suppressions etc. All Sub-Account API operations need to pass X-SubAccount-ApiKey header with every API call.

The Account API operations allow users to manage multiple sub-accounts and manage IPs. A single parent SendPost account can have 100's of sub-accounts. You may want to create sub-accounts for different products your company is running or to segregate types of emails or for managing email sending across multiple customers of yours.

SMTP Reference

Simple Mail Transfer Protocol (SMTP) is a quick and easy way to send email from one server to another. SendPost provides an SMTP service that allows you to deliver your email via our servers instead of your own client or server. This means you can count on SendPost's delivery at scale for your SMTP needs.

Integrating SMTP

Get the SMTP username and password from your SendPost account.
Set the server host in your email client or application to smtp.sendpost.io. This setting is sometimes referred to as the external SMTP server or the SMTP relay.
Set the username and password.
Set the port to 587 (or as specified below).

SMTP Ports

For an unencrypted or a TLS connection, use port 25, 2525 or 587.
For a SSL connection, use port 465
Check your firewall and network to ensure they're not blocking any of our SMTP Endpoints.

SendPost supports STARTTLS for establishing a TLS-encrypted connection. STARTTLS is a means of upgrading an unencrypted connection to an encrypted connection. There are versions of STARTTLS for a variety of protocols; the SMTP version is defined in RFC 3207.

To set up a STARTTLS connection, the SMTP client connects to the SendPost SMTP endpoint smtp.sendpost.io on port 25, 587, or 2525, issues an EHLO command, and waits for the server to announce that it supports the STARTTLS SMTP extension. The client then issues the STARTTLS command, initiating TLS negotiation. When negotiation is complete, the client issues an EHLO command over the new encrypted connection, and the SMTP session proceeds normally.

Sending email from your application

\"use strict\";

const nodemailer = require(\"nodemailer\");

async function main() {
// create reusable transporter object using the default SMTP transport
let transporter = nodemailer.createTransport({
host: \"smtp.sendpost.io\",
port: 587,
secure: false, // true for 465, false for other ports
auth: {
user:  \"<username>\" , // generated ethereal user
pass: \"<password>\", // generated ethereal password
},
requireTLS: true,
debug: true,
logger: true,
});

// send mail with defined transport object
try {
let info = await transporter.sendMail({
from: '[email protected]',
to: '[email protected]',
subject: 'Test Email Subject',
html: '<h1>Hello Geeks!!!</h1>',
});
console.log(\"Message sent: %s\", info.messageId);
} catch (e) {
console.log(e)
}
}

main().catch(console.error);

For PHP

<?php
// Import PHPMailer classes into the global namespace
use PHPMailer\\PHPMailer\\PHPMailer;
use PHPMailer\\PHPMailer\\SMTP;
use PHPMailer\\PHPMailer\\Exception;

// Load Composer's autoloader
require 'vendor/autoload.php';

$mail = new PHPMailer(true);

// Settings
try {
$mail->SMTPDebug = SMTP::DEBUG_CONNECTION;                  // Enable verbose debug output
$mail->isSMTP();                                            // Send using SMTP
$mail->Host       = 'smtp.sendpost.io';                     // Set the SMTP server to send through
$mail->SMTPAuth   = true;                                   // Enable SMTP authentication
$mail->Username   = '<username>';                           // SMTP username
$mail->Password   = '<password>';                           // SMTP password
$mail->SMTPSecure = PHPMailer::ENCRYPTION_STARTTLS;         // Enable implicit TLS encryption
$mail->Port       = 587;                                    // TCP port to connect to; use 587 if you have set `SMTPSecure = PHPMailer::ENCRYPTION_STARTTLS`

//Recipients
$mail->setFrom('[email protected]', 'Erlich');
$mail->addAddress('[email protected]', 'Gilfoyle');

//Content
$mail->isHTML(true);                                  //Set email format to HTML
$mail->Subject = 'Here is the subject';
$mail->Body    = 'This is the HTML message body <b>in bold!</b>';
$mail->AltBody = 'This is the body in plain text for non-HTML mail clients';

$mail->send();
echo 'Message has been sent';

} catch (Exception $e) {
echo \"Message could not be sent. Mailer Error: {$mail->ErrorInfo}\";
}

For Python

#!/usr/bin/python3

import sys
import os
import re

from smtplib import SMTP
import ssl

from email.mime.text import MIMEText

SMTPserver = 'smtp.sendpost.io'
PORT = 587
sender =     '[email protected]'
destination = ['[email protected]']

USERNAME = \"<username>\"
PASSWORD = \"<password>\"

# typical values for text_subtype are plain, html, xml
text_subtype = 'plain'

content=\"\"\"\\
Test message
\"\"\"

subject=\"Sent from Python\"

try:
msg = MIMEText(content, text_subtype)
msg['Subject']= subject
msg['From']   = sender

conn = SMTP(SMTPserver, PORT)
conn.ehlo()
context = ssl.create_default_context()
conn.starttls(context=context)  # upgrade to tls
conn.ehlo()
conn.set_debuglevel(True)
conn.login(USERNAME, PASSWORD)

try:
resp = conn.sendmail(sender, destination, msg.as_string())
print(\"Send Mail Response: \", resp)
except Exception as e:
print(\"Send Email Error: \", e)
finally:
conn.quit()

except Exception as e:
print(\"Error:\", e)

For Golang

package main

import (
\"fmt\"
\"net/smtp\"
\"os\"
)

// Sending Email Using Smtp in Golang

func main() {

username := \"<username>\"
password := \"<password>\"

from := \"[email protected]\"
toList := []string{\"[email protected]\"}
host := \"smtp.sendpost.io\"
port := \"587\" // recommended

// This is the message to send in the mail
msg := \"Hello geeks!!!\"

// We can't send strings directly in mail,
// strings need to be converted into slice bytes
body := []byte(msg)

// PlainAuth uses the given username and password to
// authenticate to host and act as identity.
// Usually identity should be the empty string,
// to act as username.
auth := smtp.PlainAuth(\"\", username, password, host)

// SendMail uses TLS connection to send the mail
// The email is sent to all address in the toList,
// the body should be of type bytes, not strings
// This returns error if any occured.
err := smtp.SendMail(host+\":\"+port, auth, from, toList, body)

// handling the errors
if err != nil {
fmt.Println(err)
os.Exit(1)
}

fmt.Println(\"Successfully sent mail to all user in toList\")
}

For Java

// implementation 'com.sun.mail:javax.mail:1.6.2'

import java.util.Properties;

import javax.mail.Message;
import javax.mail.Session;
import javax.mail.Transport;
import javax.mail.internet.InternetAddress;
import javax.mail.internet.MimeMessage;

public class SMTPConnect {

// This address must be verified.
static final String FROM = \"[email protected]\";
static final String FROMNAME = \"Erlich Bachman\";

// Replace [email protected] with a \"To\" address. If your account
// is still in the sandbox, this address must be verified.
static final String TO = \"[email protected]\";

// Replace smtp_username with your SendPost SMTP user name.
static final String SMTP_USERNAME = \"<username>\";

// Replace smtp_password with your SendPost SMTP password.
static final String SMTP_PASSWORD = \"<password>\";

// SMTP Host Name
static final String HOST = \"smtp.sendpost.io\";

// The port you will connect to on SendPost SMTP Endpoint.
static final int PORT = 587;

static final String SUBJECT = \"SendPost SMTP Test (SMTP interface accessed using Java)\";

static final String BODY = String.join(
System.getProperty(\"line.separator\"),
\"<h1>SendPost SMTP Test</h1>\",
\"<p>This email was sent with SendPost using the \",
\"<a href='https://github.com/eclipse-ee4j/mail'>Javamail Package</a>\",
\" for <a href='https://www.java.com'>Java</a>.\"
);

public static void main(String[] args) throws Exception {

// Create a Properties object to contain connection configuration information.
Properties props = System.getProperties();
props.put(\"mail.transport.protocol\", \"smtp\");
props.put(\"mail.smtp.port\", PORT);
props.put(\"mail.smtp.starttls.enable\", \"true\");
props.put(\"mail.smtp.debug\", \"true\");
props.put(\"mail.smtp.auth\", \"true\");

// Create a Session object to represent a mail session with the specified properties.
Session session = Session.getDefaultInstance(props);

// Create a message with the specified information.
MimeMessage msg = new MimeMessage(session);
msg.setFrom(new InternetAddress(FROM,FROMNAME));
msg.setRecipient(Message.RecipientType.TO, new InternetAddress(TO));
msg.setSubject(SUBJECT);
msg.setContent(BODY,\"text/html\");

// Create a transport.
Transport transport = session.getTransport();

// Send the message.
try {
System.out.println(\"Sending...\");

// Connect to SendPost SMTP using the SMTP username and password you specified above.
transport.connect(HOST, SMTP_USERNAME, SMTP_PASSWORD);

// Send the email.
transport.sendMessage(msg, msg.getAllRecipients());
System.out.println(\"Email sent!\");

} catch (Exception ex) {

System.out.println(\"The email was not sent.\");
System.out.println(\"Error message: \" + ex.getMessage());
System.out.println(ex);
}
// Close and terminate the connection.
}
}

Many programming languages support sending email using SMTP. This capability might be built into the programming language itself, or it might be available as an add-on, plug-in, or library. You can take advantage of this capability by sending email through SendPost from within application programs that you write.

We have provided examples in Python3, Golang, Java, PHP, JS.

API Contract Versioning (Public REST)

The public REST API uses a versioned response contract so field changes stay non-breaking:

Send X-SendPost-Public-Contract: v1 to opt into the current v1 response shape, or legacy for the pre-v1 shape. If the header is omitted, the applied contract is policy-driven — legacy before the published sunset date, v1 after it.
Every response echoes X-SendPost-Public-Contract: <applied>. When the legacy contract is served, responses also include Deprecation: true, Sunset: <RFC1123 date>, and Link: <doc-url>; rel=\"deprecation\".
Migrate to v1 before the sunset date. Notable legacy → v1 field changes: Suppression smtp_error → smtpError, Stat email_type → emailType.

X-SendPost-Private-Api: true is an internal header used only by the SendPost dashboard to receive richer internal objects. It is not part of the public SDK contract and should not be set by API integrations.

This SDK is automatically generated by the OpenAPI Generator project:

API version: 1.3.0
Package version: 3.0.0
Generator version: 7.13.0
Build package: org.openapitools.codegen.languages.JavascriptClientCodegen

Installation

For Node.js

npm

To publish the library as a npm, please follow the procedure in "Publishing npm packages".

Then install it via:

npm install sendpost-js-sdk --save

Finally, you need to build the module:

npm run build

Local development

To use the library locally without publishing to a remote npm registry, first install the dependencies by changing into the directory containing package.json (and this README). Let's call this JAVASCRIPT_CLIENT_DIR. Then run:

npm install

Next, link it globally in npm with the following, also from JAVASCRIPT_CLIENT_DIR:

npm link

To use the link you just defined in your project, switch to the directory you want to use your sendpost-js-sdk from, and run:

npm link /path/to/<JAVASCRIPT_CLIENT_DIR>

Finally, you need to build the module:

npm run build

git

If the library is hosted at a git repository, e.g.https://github.com/sendpost/sendpost-js-sdk then install it via:

    npm install sendpost/sendpost-js-sdk --save

For browser

The library also works in the browser environment via npm and browserify. After following the above steps with Node.js and installing browserify with npm install -g browserify, perform the following (assuming main.js is your entry file):

browserify main.js > bundle.js

Then include bundle.js in the HTML pages.

Webpack Configuration

Using Webpack you may encounter the following error: "Module not found: Error: Cannot resolve module", most certainly you should disable AMD loader. Add/merge the following section to your webpack config:

module: {
  rules: [
    {
      parser: {
        amd: false
      }
    }
  ]
}

Getting Started

Please follow the installation instruction and execute the following JS code:

var sendpost = require('sendpost-js-sdk');

var defaultClient = sendpost.ApiClient.instance;
// Configure API key authorization: subAccountAuth
var subAccountAuth = defaultClient.authentications['subAccountAuth'];
subAccountAuth.apiKey = "YOUR API KEY"
// Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
//subAccountAuth.apiKeyPrefix['X-SubAccount-ApiKey'] = "Token"

var api = new sendpost.DomainApi()
var createDomainRequest = new sendpost.CreateDomainRequest(); // {CreateDomainRequest} 
api.createSubAccountDomain(createDomainRequest).then(function(data) {
  console.log('API called successfully. Returned data: ' + data);
}, function(error) {
  console.error(error);
});

Documentation for API Endpoints

All URIs are relative to https://api.sendpost.io/api/v1

Class | Method | HTTP request | Description ------------ | ------------- | ------------- | ------------- sendpost.DomainApi | createSubAccountDomain | POST /subaccount/domain | Create Domain sendpost.DomainApi | deleteSubAccountDomain | DELETE /subaccount/domain/{domain_id} | Delete Domain sendpost.DomainApi | getAllDomains | GET /subaccount/domain | List Domains sendpost.DomainApi | getSubAccountDomain | GET /subaccount/domain/{domain_id} | Get Domain sendpost.EmailApi | sendEmail | POST /subaccount/email/ | Send Email sendpost.EmailApi | sendEmailWithTemplate | POST /subaccount/email/template | Send Email With Template sendpost.IPApi | allocateNewIp | PUT /account/ip/allocate | Allocate IP sendpost.IPApi | deleteIp | DELETE /account/ip/{ip_id} | Delete IP sendpost.IPApi | getAllIps | GET /account/ip/ | List IPs sendpost.IPApi | getSpecificIp | GET /account/ip/{ip_id} | Get IP sendpost.IPApi | updateIp | PUT /account/ip/{ip_id} | Update IP sendpost.IPPoolsApi | createIPPool | POST /account/ippool | Create IPPool sendpost.IPPoolsApi | deleteIPPool | DELETE /account/ippool/{ippool_id} | Delete IPPool sendpost.IPPoolsApi | getAllIPPools | GET /account/ippool | List IPPools sendpost.IPPoolsApi | getIPPoolById | GET /account/ippool/{ippool_id} | Get IPPool sendpost.IPPoolsApi | updateIPPool | PUT /account/ippool/{ippool_id} | Update IPPool sendpost.MessageApi | getAllMessages | GET /account/message | List Messages sendpost.MessageApi | getMessageById | GET /account/message/{message_id} | Get Message sendpost.StatsApi | accountSubaccountStatSubaccountIdAggregateGet | GET /account/subaccount/stat/{subaccount_id}/aggregate | Get Aggregate Stats sendpost.StatsApi | accountSubaccountStatSubaccountIdGet | GET /account/subaccount/stat/{subaccount_id} | List Stats sendpost.StatsApi | getAggregateStatsByGroup | GET /account/subaccount/stat/{subaccount_id}/group | Get Group Aggregate Stats sendpost.StatsAApi | getAccountAggregateStats | GET /account/stat/aggregate | Get Account Aggregate Stats sendpost.StatsAApi | getAccountAggregateStatsByGroup | GET /account/stat/aggregate/group | Get Account Group Aggregate Stats sendpost.StatsAApi | getAccountStatsByGroup | GET /account/stat/group | List Account Group Stats sendpost.StatsAApi | getAllAccountStats | GET /account/stat | List Account Stats sendpost.SubAccountApi | createSubAccount | POST /account/subaccount/ | Create Sub-Account sendpost.SubAccountApi | deleteSubAccount | DELETE /account/subaccount/{subaccount_id} | Delete Sub-Account sendpost.SubAccountApi | getAllSubAccounts | GET /account/subaccount/ | List Sub-Accounts sendpost.SubAccountApi | getSubAccount | GET /account/subaccount/{subaccount_id} | Get Sub-Account sendpost.SubAccountApi | updateSubAccount | PUT /account/subaccount/{subaccount_id} | Update Sub-Account sendpost.SuppressionApi | createSuppression | POST /subaccount/suppression | Create Suppressions sendpost.SuppressionApi | deleteSuppression | DELETE /subaccount/suppression | Delete Suppressions sendpost.SuppressionApi | getSuppressionList | GET /subaccount/suppression | List Suppressions sendpost.WebhookApi | createWebhook | POST /account/webhook | Create Webhook sendpost.WebhookApi | deleteWebhook | DELETE /account/webhook/{webhook_id} | Delete Webhook sendpost.WebhookApi | getAllWebhooks | GET /account/webhook | List Webhooks sendpost.WebhookApi | getWebhook | GET /account/webhook/{webhook_id} | Get Webhook sendpost.WebhookApi | updateWebhook | PUT /account/webhook/{webhook_id} | Update Webhook

Documentation for Models

Documentation for Authorization

Authentication schemes defined for the API:

accountAuth

Type: API key
API key parameter name: X-Account-ApiKey
Location: HTTP header

subAccountAuth

Type: API key
API key parameter name: X-SubAccount-ApiKey
Location: HTTP header

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

sendpost-js-sdk

Introduction

📌 API versioning & the v1 response contract

Overview

REST API

Authentication

HTTP Response Headers

API SDKs

API Reference

SMTP Reference

Integrating SMTP

SMTP Ports

Sending email from your application

API Contract Versioning (Public REST)

Installation

For Node.js

npm

Local development

git

For browser

Webpack Configuration

Getting Started

Documentation for API Endpoints

Documentation for Models

Documentation for Authorization

accountAuth

subAccountAuth