Introduction

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

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 hello@sendpost.io

• PHP
• Java
• NodeJS
• Javascript
• Ruby
• Python
• Golang
• Rust

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.

API Sub-Account

Email

This API allows you to send emails from a specific sub-account. You can specify one email recipient or multiple recipients with this API call. You can provide options for tracking opens or clicks, having dynamic custom fields or if-else conditions for email personalisation.

You can also assign various groups to each API call which will later be useful while analysing stats. Also you can specify custom headers which will be added to webhook payload on occurrence of events such as email processed, delivered, opened, clicked, bounced, unsubscribed etc.

If you are running on dedicated IP plan then you can also specify the IPPool from which emails should be sent.

Send Email

Use this API to send either a single or batch email

To send an email make a POST request as shown below:

curl -X POST "https://api.sendpost.io/api/v1/subaccount/email/"
-H  "accept: application/json"
-H  "X-SubAccount-ApiKey: <subaccount_api_key>"

The above JSON structured body needs to be posted:

{
  "from": {
    "email": "gavin@hooli.com",
    "name": "Gavin Belson"
  },
  "replyTo": {
    "email": "welcome@hooli.vom",
    "name": "Team @ Hooli"
  },
  "to": [
    {
      "email": "bighead@bachmanity.com",
      "name": "Nelson Bighetti",
      "customFields": {
         "Company": "Bachmanity"
      },
      "cc": [
        {
          "email": "dinesh@bachmanity.com",
          "name": "Dinesh",
          "customFields": {
            "Company": "Bachmanity"
          }
        }
      ],
      "bcc": [
        {
          "email": "jian@bachmanity.com",
          "name": "Jian Yang"
        }
      ]
    },
    {
      "email": "elrich@bachmanity.com",
      "name": "Elrich Bachman",
      "customFields": {
         "Company": "Bachmanity"
      }
    }
  ],
  "headers":  {
     "X-Campaign-Id": "techcrunch-launch"
  },
  "subject": "Launching Nucleus :) at TechCrunch Disrupt",
  "attachments": [
    {
      "content": "V2VsY29tZSB0byBTZW5kUG9zdCEgOikK",
      "filename": "file0.txt"
    }
  ],
  "preText": "We are launching the best cloud based compression platform",
  "htmlBody": "<html><body>Thanks for your trust in Hooli {{.FirstName}}. We are trying launching Nucleus at TechCrunch Disrupt - our cloud based compression platform</body></html>",
  "textBody": "Thanks for your trust in Hooli {{.FirstName}}. We are trying launching Nucleus at TechCrunch Disrupt - our cloud based compression platform",
  "ippool": "promotional-hooli",
  "trackClicks": true,
  "trackOpens": true,
  "groups": ["promotion", "techcrunch-launch"]
}

The above command returns JSON structured like this:

[
  {
    "to": "bighead@bachmanity.com",
    "submittedAt": 1567512491587205124,
    "messageID": "0e139af1-f1xe-480d-b08d-eg28m48kf48d",
    "errorCode": 0,
    "message": "OK"
  },
  {
    "to": "dinesh@bachmanity.com",
    "submittedAt": 1567512491587205124,
    "messageID": "sasddfa23-f1xe-480d-b08d-eg28m48kf48d",
    "errorCode": 0,
    "message": "OK"
  },
  {
    "to": "jian@bachmanity.com",
    "submittedAt": 1567512491587205124,
    "messageID": "0e1sadsa-f1xe-480d-b08d-eg28m48kf48d",
    "errorCode": 0,
    "message": "OK"
  },
  {
    "to": "elrich@bachmanity.com",
    "submittedAt": 1567512491587205024,
    "messageID": "sb121abe-e1cd-e88d-c09d-5e4g547ef409d",
    "errorCode": 0,
    "message": "OK"
  }
]

HTTP Request

POST https://api.sendpost.io/api/v1/subaccount/email/

Request Headers

Body Format

Response

The response comprises of a list of email message response objects. The email response object in the response has:

Send Email With Template

To make it easy for developers to integrate sending transactional emails, we have provided email API to send with template. SendPost has a easy-to-use drag-drop editor and tons of transactional email templates for common use-cases such as login emails, verification emails, payments, forget password emails etc.

With this API, you can just specify your template name and get started with email sending in minutes. You no longer have to specify HTML body or plain Text in your email. Another added benefit is, you can change your template HTML in realtime without any code changes.

To send an email make a POST request as shown below:

curl -X POST "https://api.sendpost.io/api/v1/subaccount/email/template"
-H  "accept: application/json"
-H  "X-SubAccount-ApiKey: <subaccount_api_key>"

The above JSON structured body needs to be posted:

{
  "from": {
    "email": "gavin@hooli.com",
    "name": "Gavin Belson"
  },
  "replyTo": {
    "email": "welcome@hooli.vom",
    "name": "Team @ Hooli"
  },
  "to": [
    {
      "email": "bighead@bachmanity.com",
      "name": "Nelson Bighetti",
      "customFields": {
         "Company": "Bachmanity"
      }
    },
    {
      "email": "elrich@bachmanity.com",
      "name": "Elrich Bachman",
      "customFields": {
         "Company": "Bachmanity"
      }
    }
  ],
  "headers":  {
     "X-Drip-Id": "onboarding-nucles-101"
  },
  "subject": "Welcome to Nucles :) Let's get started",
  "attachments": [
    {
      "content": "V2VsY29tZSB0byBTZW5kUG9zdCEgOikK",
      "filename": "file0.txt"
    }
  ],
  "preText": "Follow the steps to integrate our video compression API",
  "template": "welcome-onboarding",
  "ippool": "transactional-hooli",
  "trackClicks": true,
  "trackOpens": true,
  "groups": ["transactional", "onboarding"]
}

The above command returns JSON structured like this:

[
  {
    "to": "bighead@bachmanity.comm",
    "submittedAt": 1567512491587205124,
    "messageID": "0e139af1-f1xe-480d-b08d-eg28m48kf48d",
    "errorCode": 0,
    "message": "OK"
  },
  {
    "to": "elrich@bachmanity.com",
    "submittedAt": 1567512491587205024,
    "messageID": "sb121abe-e1cd-e88d-c09d-5e4g547ef409d",
    "errorCode": 0,
    "message": "OK"
  }
]

HTTP Request

POST https://api.sendpost.io/api/v1/subaccount/email/template

Request Headers

Body Format

Response

The response comprises of a list of email message response objects. The email response object in the response has:

Domain

This API allows you to manage your domains for a specific sub-account. Across all the requests you need to pass X-SubAccount-ApiKey header.

Get All Domains

Gets a list of all domains, their DNS records and current authentication status.

To retrieve domains make a GET request as shown below:

curl -X GET "https://api.sendpost.io/api/v1/subaccount/domain/"
-H  "accept: application/json"
-H  "X-SubAccount-ApiKey: <subaccount_api_key>"

The above command returns JSON structured like this:

[{
  "id": 117,
  "name": "piedpiper.com",
  "dkimVerified": false,
  "returnPathVerified": true,
  "trackVerified": true,
  "dkim": {
    "host": "1583302046._domainkey.piedpiper.com",
    "type": "TXT",
    "textValue": "v=DKIM1;k=rsa;s=email;h=sha256;p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDCRpSjnIkc2A4iEQfikCIIrV+CJunQfezo0i2rbpb3rAEy+2SCAB9ha5otlqRLCrsfTkuUpzwses5oTZX0ySxeDKe7o/TkDIqmSvdso9B7CFUvT2SQ9FacYzUVJ3N4ny4PiNT3iV9hh7WcfRXomARYFrcZNjbmHEV1mEVbSuiziQIDAQAB"
  },
  "returnPath": {
    "host": "sp-bounces.piedpiper.com",
    "type": "CNAME",
    "textValue": "sp.sendpost.email"
  },
  "track": {
    "host": "track.piedpiper.com",
    "type": "CNAME",
    "textValue": "api.sendpost.io"
  },
  "created": 1567512491587205024
},
{
  "id": 118,
  "name": "hooli.com",
  "dkimVerified": false,
  "returnPathVerified": true,
  "trackVerified": true,
  "dkim": {
    "host": "1587987845._domainkey.hooli.com",
    "type": "TXT",
    "textValue": "v=DKIM1;k=rsa;s=email;h=sha256;p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDsGMUVM1bqebA0bgtf0HQ6P/FZJy42k/OHP0OgVv4WMSsHOvCFre1/6d1GTx3ldeJf612K3L7wV4iJfDMh2FEpuQ+z+pOro3FarWuawoiJbBudgQQ8rResnZ4Sg3W1Zr3tcZgBCEQ9WoLDv/B2dd01p3ZJ40hsco+Fw75Ldnrd3wIDAQAB"
  },
  "returnPath": {
    "host": "sp-bounces.hooli.com",
    "type": "CNAME",
    "textValue": "sp.sendpost.email"
  },
  "track": {
    "host": "track.hooli.com",
    "type": "CNAME",
    "textValue": "api.sendpost.io"
  },
  "created": 1567512491587205024
}]

HTTP Request

GET https://api.sendpost.io/api/v1/subaccount/domain

Request Headers

Query Parameters

Response

The response comprises of a list of domains. Each domain object in the response has:

Get a Specific Domain

Get a specific domain based on the id of domain resource

To retrieve a specific domain make a GET request as shown below:

curl -X GET "https://api.sendpost.io/api/v1/subaccount/domain/<domain_id>"
-H  "accept: application/json"
-H  "X-SubAccount-ApiKey: <subaccount_api_key>"

The above command returns JSON structured like this:

{
  "id": 117,
  "name": "piedpiper.com",
  "dkimVerified": true,
  "returnPathVerified": true,
  "trackVerified": true,
  "dkim": {
    "host": "1583302046._domainkey.piedpiper.com",
    "type": "TXT",
    "textValue": "v=DKIM1;k=rsa;s=email;h=sha256;p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDCRpSjnIkc2A4iEQfikCIIrV+CJunQfezo0i2rbpb3rAEy+2SCAB9ha5otlqRLCrsfTkuUpzwses5oTZX0ySxeDKe7o/TkDIqmSvdso9B7CFUvT2SQ9FacYzUVJ3N4ny4PiNT3iV9hh7WcfRXomARYFrcZNjbmHEV1mEVbSuiziQIDAQAB"
  },
  "returnPath": {
    "host": "sp-bounces.piedpiper.com",
    "type": "CNAME",
    "textValue": "sp.sendpost.email"
  },
  "track": {
    "host": "track.piedpiper.com",
    "type": "CNAME",
    "textValue": "api.sendpost.io"
  },
  "created": 1567512491587205024
}

HTTP Request

GET https://api.sendpost.io/api/v1/subaccount/domain/<domain_id>

Request Headers

URL Parameters

Response

The response comprises of a specific domain information. The domain object in the response has:

Create a New Domain

Create a new domain based on the name of domain resource

To create a specific domain make a POST request as shown below:

curl -X POST "https://api.sendpost.io/api/v1/subaccount/domain/"
-H  "accept: application/json"
-H  "X-SubAccount-ApiKey: <subaccount_api_key>"

The above JSON structured body needs to be posted:

{
  "name": "hooli.com"
}

The above command returns JSON structured like this:

{
  "id": 117,
  "name": "hooli.com",
  "dkimVerified": true,
  "returnPathVerified": true,
  "trackVerified": true,
  "dkim": {
    "host": "1583302046._domainkey.hooli.com",
    "type": "TXT",
    "textValue": "v=DKIM1;k=rsa;s=email;h=sha256;p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDCRpSjnIkc2A4iEQfikCIIrV+CJunQfezo0i2rbpb3rAEy+2SCAB9ha5otlqRLCrsfTkuUpzwses5oTZX0ySxeDKe7o/TkDIqmSvdso9B7CFUvT2SQ9FacYzUVJ3N4ny4PiNT3iV9hh7WcfRXomARYFrcZNjbmHEV1mEVbSuiziQIDAQAB"
  },
  "returnPath": {
    "host": "sp-bounces.hooli.com",
    "type": "CNAME",
    "textValue": "sp.sendpost.email"
  },
  "track": {
    "host": "track.hooli.com",
    "type": "CNAME",
    "textValue": "api.sendpost.io"
  },
  "created": 1567512491588004044
}

HTTP Request

POST https://api.sendpost.io/api/v1/subaccount/domain/

Request Headers

Body Format

Response

The response comprises of a specific domain information. The domain object in the response has:

Delete a Specific Domain

curl "https://api.sendpost.io/api/v1/subaccount/domain/<domain_id>"
-X DELETE
-H "Authorization: <subaccount_api_key>"

The above command returns JSON structured like this:

{
  "id": 117,
  "message": "Domain (techmeme.com) has been deleted successfully"
}

This endpoint deletes a specific domain.

HTTP Request

DELETE https://api.sendpost.io/api/v1/subaccount/domain/<domain_id>

URL Parameters

Response

The response comprises of a id and name of deleted domain. The domain object in the response has:

Stat (SA)

This API allows you to get your stats for a specific sub-account. Across all the requests you need to pass X-SubAccount-ApiKey header. You will be able to see email processed, delivered, opens, clicks, hardBounce, softBounce, unsubscribe and spam complaints.

Get All Stats

Gets a list of email stats for a specific sub-account for a daterange. Both from and to date and included while returning stats response.

To retrieve Stats make a GET request as shown below:

curl -X GET "https://api.sendpost.io/api/v1/subaccount/stat?from=2020-03-12&to=2020-04-14"
-H  "accept: application/json"
-H  "X-SubAccount-ApiKey: <subaccount_api_key>"

The above command returns JSON structured like this:

[{
    "date": "2020-03-12",
    "stats": {
      "processed": 225,
      "delivered": 200,
      "dropped": 10,
      "hardBounced": 10,
      "softBounced": 5,
      "opened": 50,
      "clicked": 30,
      "unsubscribed": 5,
      "spam": 2
    }
  },
  {
    "date": "2020-03-14",
    "stats": {
      "processed": 340,
      "delivered": 300,
      "dropped": 20,
      "hardBounced": 15,
      "softBounced": 5,
      "opened": 72,
      "clicked": 47,
      "unsubscribed": 5,
      "spam": 2
    }
  }]

HTTP Request

GET https://api.sendpost.io/api/v1/subaccount/stat?from=2020-03-12&to=2020-04-14

Request Headers

Query Parameters

Response

The response comprises of a list of stat objects containing the date and email API stats for the daterange (from and to date):

Get Aggregate Stats

Gets aggregated email stats for a specific sub-account for a daterange. Both from and to date and included while returning aggregated stats response.

To retrieve Stats make a GET request as shown below:

curl -X GET "https://api.sendpost.io/api/v1/subaccount/stat/aggregate?from=2019-01-01&to=2019-12-31"
-H  "accept: application/json"
-H  "X-SubAccount-ApiKey: <subaccount_api_key>"

The above command returns JSON structured like this:

{
   "processed": 22500,
   "delivered": 20000,
   "dropped": 1000,
   "hardBounced": 1000,
   "softBounced": 500,
   "opened": 5000,
   "clicked": 3000,
   "unsubscribed": 500,
   "spam": 200
}

HTTP Request

GET https://api.sendpost.io/api/v1/subaccount/stat?from=2019-01-01&to=2019-12-31

Request Headers

Query Parameters

Response

The response comprises of a list of stat objects containing the date and email API stats for the daterange (from and to date):

Get All Stats By Group

Gets a list of email stats for a specific sub-account by group for a daterange. Both from and to date and included while returning stats response.

To retrieve Stats by Group make a GET request as shown below:

curl -X GET "https://api.sendpost.io/api/v1/subaccount/stat/group?group=shopify&from=2020-03-12&to=2020-04-14"
-H  "accept: application/json"
-H  "X-SubAccount-ApiKey: <subaccount_api_key>"

The above command returns JSON structured like this:

[{
    "date": "2020-03-12",
    "stats": {
      "processed": 225,
      "delivered": 200,
      "dropped": 10,
      "hardBounced": 10,
      "softBounced": 5,
      "opened": 50,
      "clicked": 30,
      "unsubscribed": 5,
      "spam": 2
    }
  },
  {
    "date": "2020-03-14",
    "stats": {
      "processed": 340,
      "delivered": 300,
      "dropped": 20,
      "hardBounced": 15,
      "softBounced": 5,
      "opened": 72,
      "clicked": 47,
      "unsubscribed": 5,
      "spams": 2
    }
  }]

HTTP Request

GET https://api.sendpost.io/api/v1/subaccount/stat/group?group=shopify&from=2020-03-12&to=2020-04-14

Request Headers

Query Parameters

Response

The response comprises of a list of stat objects containing the date and email API stats of a specific group for the daterange (from and to date):

Get Aggregate Stats by Group

Gets aggregated email stats for a specific group in a sub-account for the specified daterange. Both from and to date and included while returning aggregated stats response.

To retrieve Stats make a GET request as shown below:

curl -X GET "https://api.sendpost.io/api/v1/subaccount/stat/aggregate/group?group=shopify&from=2019-01-01&to=2019-12-31"
-H  "accept: application/json"
-H  "X-SubAccount-ApiKey: <subaccount_api_key>"

The above command returns JSON structured like this:

{
   "processed": 22500,
   "delivered": 20000,
   "dropped": 1000,
   "hardBounced": 1000,
   "softBounced": 500,
   "opened": 5000,
   "clicked": 3000,
   "unsubscribed": 500,
   "spam": 200
}

HTTP Request

GET https://api.sendpost.io/api/v1/subaccount/stat/group?group=shopify&from=2019-01-01&to=2019-12-31

Request Headers

Query Parameters

Response

The response comprises of a list of stat objects containing the date and email API stats belonging to specified group and for the daterange (from and to date):

Suppression

This API allows you to manage your suppressions for a specific sub-account. Across all the requests you need to pass X-SubAccount-ApiKey header.

Get All Suppressions

Gets a list of all suppressions associated with a specific sub-account.

To retrieve Suppressions make a GET request as shown below:

curl -X GET "https://api.sendpost.io/api/v1/subaccount/suppression?from=2020-03-07&to=2020-04-21"
-H  "accept: application/json"
-H  "X-SubAccount-ApiKey: <subaccount_api_key>"

The above command returns JSON structured like this:

[{
    "id": 35,
    "reason": 1,
    "email": "gilfoyle@piedpiper.com",
    "created": 1567512491588025000
  },
  {
    "id": 37,
    "reason": 0,
    "email": "jianyang@gmail.com",
    "created": 1567512491588023121
  }]

HTTP Request

GET https://api.sendpost.io/api/v1/subaccount/suppression?type=unsubscribe

Request Headers

Query Parameters

Response

The response comprises of a list of suppression objects which has email address and suppression created date in it:

Create New Suppressions

Create new suppressions by posting to the suppression resource

To create a specific suppression make a POST request as shown below:

curl -X POST "https://api.sendpost.io/api/v1/subaccount/suppression/"
-H  "accept: application/json"
-H  "X-SubAccount-ApiKey: <subaccount_api_key>"

The above JSON structured body needs to be posted:

{
  "hardBounce": [
    {
      "email": "jackbarker@hooli.com"
    },
    {
      "email": "bighead@hooli.com"
    }
  ],
  "manual": [
    {
      "email": "russhannelman@gmail.com"
    }
  ],
  "unsubscribe": [
    {
      "email": "jared@piedpiper.com"
    }
  ],
  "spamComplaint": [
    {
      "email": "gilfoyle@piedpiper.com"
    }
  ]
}

The above command returns JSON structured like this:

[
    {
      "id": 37, 
      "reason": 2,
      "email": "jackbarker@hooli.com"
      "created": 1567512491588025000 
    },
    {
      "id": 39, 
      "reason": 2,
      "email": "bighead@hooli.com"
      "created": 1567512491588025100 
    },
    {
      "id": 40, 
      "reason": 0,
      "email": "russhannelman@gmail.com"
      "created": 1567512491588025120 
    },
    {
      "id": 44, 
      "reason": 1,
      "email": "jared@piedpiper.com"
      "created": 1567512491588026727 
    },
    {
      "id": 57, 
      "reason": 3,
      "email": "gilfoyle@piedpiper.com"
      "created": 1567512491588028215 
    }
]

HTTP Request

POST https://api.sendpost.io/api/v1/subaccount/suppression/

Request Headers

Body Format

Response

The response comprises of a list of suppression objects. The suppression object in the response has:

Delete Suppressions

curl "https://api.sendpost.io/api/v1/subaccount/suppression/"
-X DELETE
-H "Authorization: <subaccount_api_key>"

The above JSON structured body needs to be posted:

{
   "suppressions": [
    {
      "email": "richard@piedpiper.com"
    },
    {
      "email": "dinesh@piedpiper.com"
    }
  ]
}

The above command returns JSON structured like this:

{
  "message": "Suppressions have been deleted successfully"
}

This endpoint can be used to delete either an individual suppression or multiple suppressions

HTTP Request

DELETE https://api.sendpost.io/api/v1/subaccount/suppression/

Response

The response comprises of a id and name of deleted suppression. The suppression object in the response has:

IPPool (SA)

This API allows you to manage your ippools for a specific sub-account. Across all the requests you need to pass X-SubAccount-ApiKey header.

Get All IPPools

Gets a list of all IPPools and information about all IPs contained in that pool.

To retrieve IPPools make a GET request as shown below:

curl -X GET "https://api.sendpost.io/api/v1/subaccount/ippool/"
-H  "accept: application/json"
-H  "X-SubAccount-ApiKey: <subaccount_api_key>"

The above command returns JSON structured like this:

[{
    "id": 746,
    "name": "PiedPiper-Transactional",
    "created": 1567512491586102044,
    "overflowPool": true,
    "ips": [
      {
        "id": 11321,
        "autoWarmupEnabled": true,
        "autoWarmupStage": 7,
        "publicIP": "52.34.11.12",
        "created": 1567512491568815272
      },
      {
        "id": 11322,
        "autoWarmupEnabled": true,
        "autoWarmupStage": 10,
        "publicIP": "34.21.14.11",
        "created": 1567512491564825232
      }
    ]
 }]

HTTP Request

GET https://api.sendpost.io/api/v1/subaccount/ippool

Request Headers

Query Parameters

Response

The response comprises of a list of ippools. Each ippool object in the response has:

Get a Specific IPPool

Get a specific ippool based on the id of ippool resource

To retrieve a specific ippool make a GET request as shown below:

curl -X GET "https://api.sendpost.io/api/v1/subaccount/ippool/<ippool_id>"
-H  "accept: application/json"
-H  "X-SubAccount-ApiKey: <subaccount_api_key>"

The above command returns JSON structured like this:

{
    "id": 746,
    "name": "PiedPiper-Transactional",
    "created": 1567512491586102044,
    "overflowPool": true,
    "ips": [
      {
        "id": 11321,
        "autoWarmupEnabled": true,
        "autoWarmupStage": 7,
        "publicIP": "52.34.11.12",
        "created": 1567512491568815272
      },
      {
        "id": 11322,
        "autoWarmupEnabled": true,
        "autoWarmupStage": 10,
        "publicIP": "34.21.14.11",
        "created": 1567512491564825232
      }
    ]
}

HTTP Request

GET https://api.sendpost.io/api/v1/subaccount/ippool/<ippool_id>

Request Headers

URL Parameters

Response

The response comprises of a specific ippool information. The ippool object in the response has:

Create a New IPPool

Create a new ippool based on the name of ippool resource

To create a specific ippool make a POST request as shown below:

curl -X POST "https://api.sendpost.io/api/v1/subaccount/ippool/"
-H  "accept: application/json"
-H  "X-SubAccount-ApiKey: <subaccount_api_key>"

The above JSON structured body needs to be posted:

{
  "name": "Marketing Promotional",
  "overflowPool": true,
  "ips": [
    {
      "publicIP": "52.13.11.14"
    },
    {
      "publicIP": "52.12.10.12"
    }
  ]
}

The above command returns JSON structured like this:

{
    "id": 756,
    "name": "Hooli-Marketing-Promotional",
    "created": 1567512491586102044,
    "overflowPool": true,
    "ips": [
      {
        "id": 11429,
        "autoWarmupEnabled": true,
        "autoWarmupStage": 0,
        "publicIP": "52.13.11.14",
        "created": 1567512491568815272
      },
      {
        "id": 11430,
        "autoWarmupEnabled": true,
        "autoWarmupStage": 0,
        "publicIP": "52.12.10.12",
        "created": 1567512491564825232
      }
    ]
}

HTTP Request

POST https://api.sendpost.io/api/v1/subaccount/ippool/

Request Headers

Body Format

Response

The response comprises of a specific ippool information. The ippool object in the response has:

Update an Existing IPPool

Update an existing ippool based on the ID of ippool resource

To update a specific ippool make a PUT request as shown below:

curl -X PUT "https://api.sendpost.io/api/v1/subaccount/ippool/<ippool_id>"
-H  "accept: application/json"
-H  "X-SubAccount-ApiKey: <subaccount_api_key>"

The above JSON structured body needs to be posted:

{
  "name": "Hooli-Marketing-Promotional",
  "overflowPool": false,
  "ips": [
    {
      "publicIP": "52.12.10.12"
    },
    {
      "publicIP": "52.10.12.17"
    },
    {
      "publicIP": "35.11.10.5"
    }
  ]
}

The above command returns JSON structured like this:

{
    "id": 756,
    "name": "Hooli-Marketing-Promotional",
    "created": 1567512491586102044,
    "overflowPool": true,
    "ips": [
      {
        "id": 11429,
        "autoWarmupEnabled": true,
        "autoWarmupStage": 5,
        "publicIP": "52.12.10.12",
        "created": 1567512491588017564
      },
      {
        "id": 11530,
        "autoWarmupEnabled": true,
        "autoWarmupStage": 0,
        "publicIP": "52.10.12.17",
        "created": 1567512491568815272
      },
      {
        "id": 11531,
        "autoWarmupEnabled": true,
        "autoWarmupStage": 0,
        "publicIP": "35.11.10.5",
        "created": 1567512491568025264
      }
    ]
}

HTTP Request

PUT https://api.sendpost.io/api/v1/subaccount/ippool/<ippool_id>

Request Headers

Body Format

Response

The response comprises of a specific ippool information. The ippool object in the response has:

Delete a Specific IPPool

curl "https://api.sendpost.io/api/v1/subaccount/ippool/<ippool_id>"
-X DELETE
-H "Authorization: <subaccount_api_key>"

The above command returns JSON structured like this:

{
  "id": 756,
  "message": "IPPool (Marketing Promotional) has been deleted successfully"
}

This endpoint deletes a specific ippool.

HTTP Request

DELETE https://api.sendpost.io/api/v1/subaccount/ippool/<ippool_id>

URL Parameters

Response

The response comprises of a id and name of deleted ippool. The ippool object in the response has:

API Account

IP

This API allows you to manage your ips for a specific account. Across all the requests you need to pass X-Account-ApiKey header.

Get All IPs

Gets a list of all IPs and information about all IPs associated with a main account.

To retrieve IPs make a GET request as shown below:

curl -X GET "https://api.sendpost.io/api/v1/account/ip/"
-H  "accept: application/json"
-H  "X-Account-ApiKey: <subaccount_api_key>"

The above command returns JSON structured like this:

[{
  "id": 11321,
  "autoWarmupEnabled": true,
  "autoWarmupStage": 7,
  "publicIP": "52.34.11.12",
  "created": 1567512491588018064
},
{
  "id": 11322,
  "autoWarmupEnabled": true,
  "autoWarmupStage": 10,
  "publicIP": "34.21.14.11",
  "created": 1567512491588017564
}]

HTTP Request

GET https://api.sendpost.io/api/v1/account/ip

Request Headers

Query Parameters

Response

The response comprises of a list of ips. Each ip object in the response has:

Get a Specific IP

Get a specific ip based on the id of ip resource

To retrieve a specific ip make a GET request as shown below:

curl -X GET "https://api.sendpost.io/api/v1/account/ip/<ip_id>"
-H  "accept: application/json"
-H  "X-Account-ApiKey: <account_api_key>"

The above command returns JSON structured like this:

{
  "id": 11322,
  "autoWarmupEnabled": true,
  "autoWarmupStage": 10,
  "publicIP": "34.21.14.11",
  "created": 1567512491588017564
}

HTTP Request

GET https://api.sendpost.io/api/v1/account/ip/<ip_id>

Request Headers

URL Parameters

Response

The response comprises of a specific ip information. The ip object in the response has:

Allocate a New IP

Allocate a new IP.

To allocate a specific ip make a PUT request as shown below:

curl -X PUT "https://api.sendpost.io/api/v1/account/ip/allocate"
-H  "accept: application/json"
-H  "X-Account-ApiKey: <account_api_key>"

The above command returns JSON structured like this:

{
  "id": 11322,
  "autoWarmupEnabled": true,
  "autoWarmupStage": 10,
  "publicip": "34.21.14.11",
  "created": 1567512491588017564
}

HTTP Request

POST https://api.sendpost.io/api/v1/account/ip/allocate

Request Headers

Body Format

Response

The response comprises of a specific ip information. The ip object in the response has:

Update an Existing IP

Update an existing ip based on the ID of ip resource

To update a specific ip make a PUT request as shown below:

curl -X PUT "https://api.sendpost.io/api/v1/account/ip/<ip_id>"
-H  "accept: application/json"
-H  "X-Account-ApiKey: <account_api_key>"

The above JSON structured body needs to be posted:

{
  "autoWarmupEnabled": false
}

HTTP Request

PUT https://api.sendpost.io/api/v1/account/ip/<ip_id>

Request Headers

Body Format

> The above command returns JSON structured like this:

{
  "id": 11322,
  "autoWarmupEnabled": false,
  "autoWarmupStage": 10,
  "publicip": "34.21.14.11",
  "created": 1567512491588017564
}

HTTP Request

PUT https://api.sendpost.io/api/v1/account/ip/<ip_id>

Request Headers

Response

The response comprises of a specific ip information. The ip object in the response has:

Delete a Specific IP

curl "https://api.sendpost.io/api/v1/account/ip/<ip_id>"
-X DELETE
-H "Authorization: <account_api_key>"

The above command returns JSON structured like this:

{
  "id": 11322,
  "message": "IP (34.21.14.11) has been deleted successfully"
}

This endpoint deletes a specific ip.

HTTP Request

DELETE https://api.sendpost.io/api/v1/account/ip/<ip_id>

URL Parameters

Response

The response comprises of a id and name of deleted ip. The ip object in the response has:

IPPool (A)

This API allows you to manage your ippools for a specific account. Across all the requests you need to pass X-Account-ApiKey header.

Get All IPPools

Gets a list of all IPPools and information about all IPs contained in that pool.

To retrieve IPPools make a GET request as shown below:

curl -X GET "https://api.sendpost.io/api/v1/account/ippool/"
-H  "accept: application/json"
-H  "X-Account-ApiKey: <account_api_key>"

The above command returns JSON structured like this:

[{
    "id": 746,
    "name": "Transactional",
    "created": 1567512491586102044,
    "overflowPool": true,
    "ips": [
      {
        "id": 11321,
        "autoWarmupEnabled": true,
        "autoWarmupStage": 7,
        "publicIP": "52.34.11.12",
        "created": 1567512491568815272
      },
      {
        "id": 11322,
        "autoWarmupEnabled": true,
        "autoWarmupStage": 10,
        "publicIP": "34.21.14.11",
        "created": 1567512491564825232
      }
    ]
 }]

HTTP Request

GET https://api.sendpost.io/api/v1/account/ippool

Request Headers

Query Parameters

Response

The response comprises of a list of ippools. Each ippool object in the response has:

Get a Specific IPPool

Get a specific ippool based on the id of ippool resource

To retrieve a specific ippool make a GET request as shown below:

curl -X GET "https://api.sendpost.io/api/v1/account/ippool/<ippool_id>"
-H  "accept: application/json"
-H  "X-Account-ApiKey: <account_api_key>"

The above command returns JSON structured like this:

{
    "id": 746,
    "name": "Transactional",
    "created": 1567512491586102044,
    "overflowPool": true,
    "ips": [
      {
        "id": 11321,
        "autoWarmupEnabled": true,
        "autoWarmupStage": 7,
        "publicIP": "52.34.11.12",
        "created": 1567512491568815272
      },
      {
        "id": 11322,
        "autoWarmupEnabled": true,
        "autoWarmupStage": 10,
        "publicIP": "34.21.14.11",
        "created": 1567512491564825232
      }
    ]
}

HTTP Request

GET https://api.sendpost.io/api/v1/account/ippool/<ippool_id>

Request Headers

URL Parameters

Response

The response comprises of a specific ippool information. The ippool object in the response has:

Create a New IPPool

Create a new ippool based on the name of ippool resource

To create a specific ippool make a POST request as shown below:

curl -X POST "https://api.sendpost.io/api/v1/account/ippool/"
-H  "accept: application/json"
-H  "X-Account-ApiKey: <account_api_key>"

The above JSON structured body needs to be posted:

{
  "name": "Marketing Promotional",
  "overflowPool": true,
  "ips": [
    {
      "publicIP": "52.13.11.14"
    },
    {
      "publicIP": "52.12.10.12"
    }
  ]
}

The above command returns JSON structured like this:

{
    "id": 756,
    "name": "Marketing Promotional",
    "created": 1567512491586102044,
    "overflowPool": true,
    "ips": [
      {
        "id": 11429,
        "autoWarmupEnabled": true,
        "autoWarmupStage": 0,
        "publicIP": "52.13.11.14",
        "created": 1567512491568815272
      },
      {
        "id": 11430,
        "autoWarmupEnabled": true,
        "autoWarmupStage": 0,
        "publicIP": "52.12.10.12",
        "created": 1567512491564825232
      }
    ]
}

HTTP Request

POST https://api.sendpost.io/api/v1/account/ippool/

Request Headers

Body Format

Response

The response comprises of a specific ippool information. The ippool object in the response has:

Update an Existing IPPool

Update an existing ippool based on the ID of ippool resource

To update a specific ippool make a PUT request as shown below:

curl -X PUT "https://api.sendpost.io/api/v1/account/ippool/<ippool_id>"
-H  "accept: application/json"
-H  "X-Account-ApiKey: <account_api_key>"

The above JSON structured body needs to be posted:

{
  "name": "Marketing Promotional",
  "overflowPool": false,
  "ips": [
    {
      "publicIP": "52.12.10.12"
    },
    {
      "publicIP": "52.10.12.17"
    },
    {
      "publicIP": "35.11.10.5"
    }
  ]
}

The above command returns JSON structured like this:

{
    "id": 756,
    "name": "Marketing Promotional",
    "created": 1567512491586102044,
    "overflowPool": true,
    "ips": [
      {
        "id": 11429,
        "autoWarmupEnabled": true,
        "autoWarmupStage": 5,
        "publicIP": "52.12.10.12",
        "created": 1567512491588017564
      },
      {
        "id": 11530,
        "autoWarmupEnabled": true,
        "autoWarmupStage": 0,
        "publicIP": "52.10.12.17",
        "created": 1567512491568815272
      },
      {
        "id": 11531,
        "autoWarmupEnabled": true,
        "autoWarmupStage": 0,
        "publicIP": "35.11.10.5",
        "created": 1567512491568025264
      }
    ]
}

HTTP Request

PUT https://api.sendpost.io/api/v1/account/ippool/<ippool_id>

Request Headers

Body Format

Response

The response comprises of a specific ippool information. The ippool object in the response has:

Delete a Specific IPPool

curl "https://api.sendpost.io/api/v1/account/ippool/<ippool_id>"
-X DELETE
-H "Authorization: <account_api_key>"

The above command returns JSON structured like this:

{
  "id": 756,
  "message": "IPPool (Marketing Promotional) has been deleted successfully"
}

This endpoint deletes a specific ippool.

HTTP Request

DELETE https://api.sendpost.io/api/v1/account/ippool/<ippool_id>

URL Parameters

Response

The response comprises of a id and name of deleted ippool. The ippool object in the response has:

Stat (A)

This API allows you to get your stats for a specific account. Across all the requests you need to pass X-Account-ApiKey header. You will be able to see email processed, delivered, opens, clicks, hardBounce, softBounce, unsubscribe and spam complaints for the specific account.

Get All Account Stats

Gets a list of email stats for all sub-accounts of a specific account for a given daterange. Both from and to date are included while returning stats response.

To retrieve Stats make a GET request as shown below:

curl -X GET "https://api.sendpost.io/api/v1/account/stat?from=2020-03-12&to=2020-04-14"
-H  "accept: application/json"
-H  "X-SubAccount-ApiKey: <subaccount_api_key>"

The above command returns JSON structured like this:

[{
    "date": "2020-03-12",
    "stats": {
      "processed": 1225,
      "delivered": 1200,
      "dropped": 10,
      "hardBounced": 10,
      "softBounced": 5,
      "opens": 150,
      "clicks": 130,
      "unsubscribed": 15,
      "spams": 12
    }
  },
  {
    "date": "2020-03-14",
    "stats": {
      "processed": 1340,
      "delivered": 1300,
      "dropped": 20,
      "hardBounced": 15,
      "softBounced": 5,
      "opens": 172,
      "clicks": 147,
      "unsubscribed": 5,
      "spams": 2
    }
  }]

HTTP Request

GET https://api.sendpost.io/api/v1/account/stat?from=2020-03-12&to=2020-04-14

Request Headers

Query Parameters

Response

The response comprises of a list of stat objects containing the date and email API stats for the daterange (from and to date):

Get Account Aggregate Stats

Gets aggregated email stats for a all sub-accounts of a specific account for a given daterange. Both from and to date are included while returning aggregated stats response.

To retrieve Account Stats make a GET request as shown below:

curl -X GET "https://api.sendpost.io/api/v1/account/stat/aggregate?from=2019-01-01&to=2019-12-31"
-H  "accept: application/json"
-H  "X-SubAccount-ApiKey: <subaccount_api_key>"

The above command returns JSON structured like this:

{
   "processed": 22500,
   "delivered": 20000,
   "dropped": 1000,
   "hardBounced": 1000,
   "softBounced": 500,
   "opens": 5000,
   "clicks": 3000,
   "unsubscribed": 500,
   "spams": 200
}

HTTP Request

GET https://api.sendpost.io/api/v1/account/stat?from=2019-01-01&to=2019-12-31

Request Headers

Query Parameters

Response

The response comprises of a list of stat objects containing the date and email API stats for the daterange (from and to date):

Get All Account Stats By Group

Gets a list of all email stats for a all sub-accounts of a specific account by group for a given daterange. Both from and to date and included while returning stats response.

To retrieve Account Stats by Group make a GET request as shown below:

curl -X GET "https://api.sendpost.io/api/v1/account/stat/group?group=shopify&from=2020-03-12&to=2020-04-14"
-H  "accept: application/json"
-H  "X-Account-ApiKey: <account_api_key>"

The above command returns JSON structured like this:

[{
    "date": "2020-03-12",
    "stats": {
      "processed": 1225,
      "delivered": 1200,
      "dropped": 10,
      "hardBounced": 10,
      "softBounced": 5,
      "opens": 50,
      "clicks": 30,
      "unsubscribed": 5,
      "spams": 2
    }
  },
  {
    "date": "2020-03-14",
    "stats": {
      "processed": 1340,
      "delivered": 1300,
      "dropped": 20,
      "hardBounced": 15,
      "softBounced": 5,
      "opens": 72,
      "clicks": 47,
      "unsubscribed": 5,
      "spams": 2
    }
  }]

HTTP Request

GET https://api.sendpost.io/api/v1/account/stat/group?group=shopify&from=2020-03-12&to=2020-04-14

Request Headers

Query Parameters

Response

The response comprises of a list of stat objects containing the date and email API stats of a specific group for the daterange (from and to date):

Get Account Aggregate Stats by Group

Gets aggregated email stats for a specific group in all sub-accounts of a specific account for the given daterange. Both from and to date and included while returning aggregated stats response.

To retrieve Account Stats make a GET request as shown below:

curl -X GET "https://api.sendpost.io/api/v1/account/stat/aggregate/group?group=shopify&from=2019-01-01&to=2019-12-31"
-H  "accept: application/json"
-H  "X-Account-ApiKey: <account_api_key>"

The above command returns JSON structured like this:

{
   "processed": 122500,
   "delivered": 120000,
   "dropped": 1000,
   "hardBounced": 1000,
   "softBounced": 500,
   "opens": 5000,
   "clicks": 3000,
   "unsubscribed": 500,
   "spams": 200
}

HTTP Request

GET https://api.sendpost.io/api/v1/account/stat/group?group=shopify&from=2019-01-01&to=2019-12-31

Request Headers

Query Parameters

Response

The response comprises of a list of stat objects containing the date and email API stats belonging to specified group and for the daterange (from and to date):

Sub-Account

This API allows you to manage your subaccounts for a specific sub-account. Across all the requests you need to pass X-Account-ApiKey header.

Get All Sub-Accounts

Gets a list of all sub-accounts associated with a specific account.

To retrieve sub-accounts make a GET request as shown below:

curl -X GET "https://api.sendpost.io/api/v1/account/subaccount/"
-H  "accept: application/json"
-H  "X-Account-ApiKey: <account_api_key>"

The above command returns JSON structured like this:

[{
    "id": 11,
    "name": "Hooli",
    "created": 1567512491586102044,
    "apiKey": "AHZ3125333JHEP"
 },
 {
    "id": 12,
    "name": "PiedPiper",
    "created": 1567512491586102144,
    "apiKey": "SIZ3148343JSEP"
}]

HTTP Request

GET https://api.sendpost.io/api/v1/account/subaccount

Request Headers

Query Parameters

Response

The response comprises of a list of sub-accounts. Each sub-account object in the response has:

Get a Specific Sub-Account

Get a specific sub-account based on the id of sub-account resource

To retrieve a specific sub-account make a GET request as shown below:

curl -X GET "https://api.sendpost.io/api/v1/account/subaccount/<subaccount_id>"
-H  "accept: application/json"
-H  "X-Account-ApiKey: <account_api_key>"

The above command returns JSON structured like this:

{
    "id": 11,
    "name": "Hooli",
    "created": 1567512491586102044,
    "apiKey": "AHZ3125333JHEP"
}

HTTP Request

GET https://api.sendpost.io/api/v1/account/subaccount/<subaccount_id>

Request Headers

URL Parameters

Response

The response comprises of a specific sub-account information. The sub-account object in the response has:

Create a New Sub-Account

Create a new sub-account based on the name of sub-account resource

To create a specific sub-account make a POST request as shown below:

curl -X POST "https://api.sendpost.io/api/v1/account/subaccount/"
-H  "accept: application/json"
-H  "X-Account-ApiKey: <account_api_key>"

The above JSON structured body needs to be posted:

{
  "name": "FoxHole"
}

The above command returns JSON structured like this:

{
    "id": 12,
    "name": "FoxHole",
    "created": 1567512491586102044,
    "apiKey": "HHZ3L45E5333JIOS"
}

HTTP Request

POST https://api.sendpost.io/api/v1/account/subaccount/

Request Headers

Body Format

Response

The response comprises of a specific sub-account information. The sub-account object in the response has:

Update an Existing Sub-Account

Update an existing sub-account based on the ID of sub-account resource

To update a specific sub-account make a PUT request as shown below:

curl -X PUT "https://api.sendpost.io/api/v1/account/subaccount/<subaccount_id>"
-H  "accept: application/json"
-H  "X-Account-ApiKey: <account_api_key>"

The above JSON structured body needs to be posted:

{
  "name": "FoxHole V1"
}

The above command returns JSON structured like this:

{
    "id": 12,
    "name": "FoxHole V1",
    "created": 1567512491586102044,
    "apiKey": "HHZ3L45E5333JIOS"
}

HTTP Request

PUT https://api.sendpost.io/api/v1/account/subaccount/<subaccount_id>

Request Headers

Body Format

Response

The response comprises of a specific sub-account information. The sub-account object in the response has:

Delete a Specific Sub-Account

curl "https://api.sendpost.io/api/v1/account/subaccount/<subaccount_id>"
-X DELETE
-H "Authorization: <account_api_key>"

The above command returns JSON structured like this:

{
  "id": 12,
  "message": "Sub-Account (FoxHole V1) has been deleted successfully"
}

This endpoint deletes a specific sub-account.

HTTP Request

DELETE https://api.sendpost.io/api/v1/account/subaccount/<subaccount_id>

URL Parameters

Response

The response comprises of a id and name of deleted sub-account. The sub-account object in the response has:

Message

This API allows you to manage your messages for a specific account. Across all the requests you need to pass X-Account-ApiKey header.

Get All Messages

Gets a list of all Messages and metadata associated with them

To retrieve Messages make a GET request as shown below:

curl -X GET "https://api.sendpost.io/api/v1/account/message?from=2020-03-10&to=2020-04-10"
-H  "accept: application/json"
-H  "X-SubAccount-ApiKey: <account_api_key>"

The above command returns JSON structured like this:

[
  {
    "messageID": "4d9c5148-63fc-4999-99ea-fc997b0a24e2",
    "submittedAt": 1588760624008835220,
    "from": {
      "name": "PiedPipers",
      "email": "team@piedpiper.com"
    },
    "replyTo": {
      "name": "PiedPipers",
      "email": "team@piedpiper.com"
    },
    "to": {
      "name": "Peter Gregory",
      "email": "peter@hooli.com",
      "customFields": {
        "Company": "Hooli"
      }
    },
    "groups": [],
    "ippool": "transactional-piedpiper",
    "headers": {
      "X-Campaign-Id": "user-onboarding"
    },
    "subject": "Welcome to Pied Piper :) + 1 quick question",
    "preText": "Congrats and get some Pied Piper cred inside",
    "htmlBody": "Pied Piper has changed many landscapes. Compression. Data. The Internet",
    "textBody": "Thanks for joining Pied Piper. Pied Piper has built world's best compression technology and decentralised internet",
    "trackOpens": true,
    "trackClicks": true
  },
  {
    "messageID": "600d2ce7-e79f-4f0a-a8a0-b21eeb7c7356",
    "submittedAt": 1588760679369379774,
    "from": {
      "name": "PiedPipers",
      "email": "team@piedpiper.com"
    },
    "replyTo": {
      "name": "PiedPipers",
      "email": "welcome@piedpiper.com"
    },
    "to": {
      "name": "Gavin Belson",
      "email": "gavin@hooli.io",
      "customFields": {
        "Company": "Hooli"
      }
    },
    "groups": [],
    "ippool": "transactional-piedpiper",
    "headers": {
      "X-Campaign-Id": "user-onboarding"
    },
    "subject": "Welcome to Pied Piper :) + 1 quick question",
    "preText": "Congrats and get some Pied Piper cred inside",
    "htmlBody": "Thanks for joining Pied Piper {{.FirstName}}.Pied Piper has changed many landscapes. Compression. Data. The Internet",
    "textBody": "Thanks for joining Pied Piper {{.FirstName}}.Pied Piper has changed many landscapes. Compression. Data. The Internet",
    "trackOpens": true,
    "trackClicks": true
  }
]

HTTP Request

GET https://api.sendpost.io/api/v1/account/message

Request Headers

Query Parameters

Response

The response comprises of a list of messages. Each message object in the response has:

Get a Specific Message

Get a specific detailed message based on the id of message resource

To retrieve a specific message make a GET request as shown below:

curl -X GET "https://api.sendpost.io/api/v1/account/message/<message_id>"
-H  "accept: application/json"
-H  "X-Account-ApiKey: <account_api_key>"

The above command returns JSON structured like this:

{
    "id": 1000412,
    "submittedAt": 1567512491587205024,
    "from": "hello@hooli.com",
    "to": "larry@google.com",
    "groups": ["transactional", "fortune500"],
    "subject": "Another Hooli Moonshot ... {{.FirstName}}",
    "headers": {
        "X-Customer-ID": "Customer-111",
        "X-Campaign-ID": "11474"
    },
    "customFields": {
        "FirstName": "Larry",
        "Designation": "CEO"
    },
    "preText": "deep analysis on longevity project of hooli",
    "htmlBody": "<html><body>We have done some deep research on achieveing immortality by plasma reingestion in human body. Care to discuss over coffee at Freddie's on Friday at 7 PM?</body></html>",
    "textBody": "We have done some deep research on achieveing immortality by plasma reingestion in human body. Care to discuss over coffee at Freddie's on Friday at 7 PM?",
    "trackOpens": true,
    "trackClicks": false
}

HTTP Request

GET https://api.sendpost.io/api/v1/account/message/<message_id>

Request Headers

URL Parameters

Response

The response comprises of a specific message information. The message object in the response has:

Validations

This API allows you to manage the List Validations for your account. It allows you to upload a list to validate and get all validations done by you.Across all the requests you need to pass X-Account-ApiKey header.

Get All Validations

Gets a list of all email list validations done by your account.

To retrieve all validations make a GET request as shown below:

curl -X GET "https://api.sendpost.io/api/v1/subaccount/validation?offset=0&limit=10"
-H  "accept: application/json"
-H  "X-Account-ApiKey: <account_api_key>"

The above command returns JSON structured like this:

[{
    "id": 35,
    "reason": 1,
    "email": "peter@hoolo.com",
    "error": "",
    "created": 1567512491588025000
  },
  {
    "id": 37,
    "reason": 0,
    "email": "richard@peedpeeper.com",
    "created": 1567512491588023121
  }]

HTTP Request

GET https://api.sendpost.io/api/v1/account/validation

Request Headers

Query Parameters

Response

The response comprises of a list of validation objects which has email address and suppression created date in it:

Delete Validation

curl "https://api.sendpost.io/api/v1/account/validation/"
-X DELETE
-H "Authorization: <account_api_key>"

The above JSON structured body needs to be posted:

{
  "emails": [
    "jared@hooli.com"
  ]
}

The above command returns JSON structured like this:

{
  "message": "Validations have been deleted successfully"
}

This endpoint can be used to delete either an individual validation or multiple validation

HTTP Request

DELETE https://api.sendpost.io/api/v1/account/validation/

Response

The response comprises of a id and name of deleted validation. The validation object in the response has:

Validate

This api can be used to validate an email list which can either be in the form of an array list or a csv for much larger lists. Create new validations by posting to the validate resource. Please not the below api can be used for an array size of upto 100 emails for anything above that use the bulk request

To create a specific validation make a POST request as shown below:

 curl -X POST "https://api.sendpost.io/api/v1/account/validate/"
 -H  "accept: application/json"
 -H  "X-Account-ApiKey: <account_api_key>"

The above JSON structured body needs to be posted:

 {
    "emailIds": [
      "jared@hooli.com",
      "gavin@hooli.com",
      "peter@hooli.com",
      "jinyang@hooli.com"
    ] 
 }

The above command returns JSON structured like this:

 {
  "valid": [
     "gavin@hooli.com",
     "peter@hooli.com"
    ],
  "invalid": [
   "jinyang@hooli.com",
   "jared@hooli.com"
  ],
   "detailedResponse": [
       {
        "email":"gavin@hooli.com",
        "error": "",
        "valid": true,
        "reason": ""
       },
       {
         "email": "jinyang@hooli.com",
         "error": "",
         "valid": "false",
         "reason": "Email does not exist"
       },
       {
         "email": "peter@hooli.com",
         "valid": "true",
         "error": "",
         "reason": ""
       },
       {
        "email": "jared@hooli.com",
        "valid": "false",
        "error": "hardbounce",
        "reason": "Email does not exist"
      }    
  ] 
 }

HTTP Request

POST https://api.sendpost.io/api/v1/account/validate/

Request Headers

Body Format

Response

The response comprises of a list of validation objects. The validation object in the response has:

detailedResponse object

Bulk Validations

If you have a large email list of more than a hundred emails you can upload an email list csv to this endpoint. This api works asyncronously It will send back a job_id and once the csv processing is finished we will send a csv containing the details of the list to all members of your account via an email.

To create a bulk validation make a POST request as shown below:

 curl -X POST "https://api.sendpost.io/api/v1/account/validate/bulk"
 -H  "accept: application/json"
 -H  "X-Account-ApiKey: <account_api_key>"

The above below multipart form needs to be posted:

    fileinput:piedpiper.csv

The above command returns JSON structured like this:

 {
   "job_id": 1,
   "message": "ok"
 }

HTTP Request

POST https://api.sendpost.io/api/v1/account/validate/bulk

Request Headers

Body Format

Response

The response gives the jobid and a success message

Webhook

This API allows you to manage your webhooks for a specific account. Across all the requests you need to pass X-Account-ApiKey header.

Get All Webhooks

Gets a list of all webhooks, their endpoint and events for which they are active

To retrieve webhooks make a GET request as shown below:

curl -X GET "https://api.sendpost.io/api/v1/account/webhook/"
-H  "accept: application/json"
-H  "X-Account-ApiKey: <account_api_key>"

The above command returns JSON structured like this:

[{
  "id": 117,
  "enabled": true,
  "url": "https://app.hooli.com/email/webhook",
  "processed": true,
  "delivered": true,
  "dropped": false,
  "softBounced": false,
  "hardBounced": true,
  "opened": true,
  "clicked": true,
  "unsubscribed": true,
  "spam": true,
  "created": 1567512491588004044
}]

HTTP Request

GET https://api.sendpost.io/api/v1/account/webhook

Request Headers

Query Parameters

Response

The response comprises of a list of webhooks. Each webhook object in the response has:

Get a Specific Webhook

Get a specific webhook based on the id of webhook resource

To retrieve a specific webhook make a GET request as shown below:

curl -X GET "https://api.sendpost.io/api/v1/account/webhook/<webhook_id>"
-H  "accept: application/json"
-H  "X-Account-ApiKey: <account_api_key>"

The above command returns JSON structured like this:

{
  "id": 117,
  "enabled": true,
  "url": "https://app.piedpiper.com/email/webhook",
  "processed": true,
  "delivered": true,
  "dropped": false,
  "softBounced": false,
  "hardBounced": true,
  "opened": true,
  "clicked": true,
  "unsubscribed": true,
  "spam": true,
  "created": 1567512491588004044
}

HTTP Request

GET https://api.sendpost.io/api/v1/account/webhook/<webhook_id>

Request Headers

URL Parameters

Response

The response comprises of a specific webhook information. The webhook object in the response has:

Create a New Webhook

Create a new webhook based on the name of webhook resource

To create a specific webhook make a POST request as shown below:

curl -X POST "https://api.sendpost.io/api/v1/account/webhook/"
-H  "accept: application/json"
-H  "X-SubAccount-ApiKey: <account_api_key>"

The above JSON structured body needs to be posted:

{
  "enabled": true,
  "url": "https://app.hooli.com/email/webhook",
  "processed": true,
  "delivered": true,
  "dropped": false,
  "softBounced": false,
  "hardBounced": true,
  "opened": true,
  "clicked": true,
  "unsubscribed": true,
  "spam": true
}

The above command returns JSON structured like this:

{
  "id": 117,
  "enabled": true,
  "url": "https://app.hooli.com/email/webhook",
  "processed": true,
  "delivered": true,
  "dropped": false,
  "softBounced": false,
  "hardBounced": true,
  "opened": true,
  "clicked": true,
  "unsubscribed": true,
  "spam": true,
  "created": 1567512491588004044
}

HTTP Request

POST https://api.sendpost.io/api/v1/account/webhook/

Request Headers

Body Format

Response

The response comprises of a specific webhook information. The webhook object in the response has:

Update an Existing Webhook

Update an existing webhook based on the ID of webhook resource

To update a specific webhook make a PUT request as shown below:

curl -X PUT "https://api.sendpost.io/api/v1/account/webhook/<webhook_id>"
-H  "accept: application/json"
-H  "X-Account-ApiKey: <account_api_key>"

The above JSON structured body needs to be posted:

{
  "name": "piedPiperDeviveribility",
  "type": "sa",
  "parameter": 1,
  "entityValue":1, 
  "threshold": "50",
  "notificationType": 1,
  "emails": ["dinesh@piedpiper.com","richard@piedpiper.com"]
}

The above command returns JSON structured like this:

{
  "id": 117,
  "enabled": false,
  "url": "https://app.hooli.com/email/webhook",
  "processed": false,
  "delivered": true,
  "dropped": false,
  "softBounced": false,
  "hardBounced": true,
  "opened": true,
  "clicked": true,
  "unsubscribed": true,
  "spam": true,
  "created": 1567512491588004044
}

HTTP Request

PUT https://api.sendpost.io/api/v1/account/webhook/<webhook_id>

Request Headers

Body Format

Response

The response comprises of a specific webhook information. The webhook object in the response has:

Delete a Specific Webhook

curl "https://api.sendpost.io/api/v1/account/webhook/<webhook_id>"
-X DELETE
-H "Authorization: <account_api_key>"

The above command returns JSON structured like this:

{
  "id": 117,
  "message": "Webhook (https://app.piedpiper.com/email/webhook) has been deleted successfully"
}

This endpoint deletes a specific webhook.

HTTP Request

DELETE https://api.sendpost.io/api/v1/account/webhook/<webhook_id>

URL Parameters

Response

The response comprises of a id and name of deleted webhook. The webhook object in the response has:

Webhook Reference

Webhooks are a HTTP Post request made to your application endpoint when an interesting event happens at SendPost. This includes events such as email opens, clicks, hard bounce, spam, unsubscribe and more.

You may want to consume webhook events if you want to replicate state of your email recipients to your internal system ( have they unsubcribed or has their email bounced ?) or you want to build custom analytics for internal product consumption.

Other use-cases where consuming webhook may be relevant is when you are building an application on top of SendPost such as an email marketing software and you want to show emails delivered, opened, clicked etc. to your customers.

Testing Webhooks

Generally configuring a webhook is pretty cumbersome process for developers. At SendPost we have tried to make it a bit simpler:

• Webhook Single-Click Test

You can go to SendPost dashboard and click on button to test individual webhook. This will trigger a test Webhook API call of the specific event such as email open, click etc.

• Request Bin

RequestBin is a great service to inspect HTTP requests. You can create a temporary RequestBin URL and use the temporary URL as your webhook URL in SendPost.

After that you can trigger webhook calls either using curl or through our Webhook Single-Click Test. RequestBin will then record the HTTP requests and allow you to inspect the HTTP requests to verify headers, JSON body, and other information about the webhook request.

This will provide you with information about the HTTP requests used in the webhook if you don’t have a public URL set up yet and want to start developing right away.

Webhook POST Object

Irrespective of the type of event happening on SendPost, the webhook object returned has a consistent structure. It will have an event and emailMessage object contained in it.

The above JSON structured object is posted by SendPost webhook

{
   "event": {
      "eventID": "edhg-123gh-afasdf-124egh",
      "groups": ["transactional", "user-onboarding"],
      "subAccountID": 117,
      "messageID": "mjhl-1401-sasdf-129324",
      "type": 2,
      "submittedAt": 1567512491587205024,
      "eventMetadata": {
          "url": "",
          "smtpCode": "200",
          "smtpDescription": "email delivered successfully",
          "userAgent": {
            "family": ""
          },
          "os": {
            "family": ""
          },
          "device": {
            "family": ""
          },
          "geo": {
            "city": "",
            "state": "",
            "country": "",
            "postalCode": ""
           }
      }
   },
   "emailMessage": {
      "messageID": "mjhl-1401-sasdf-129324",
      "subAccountID": 117,
      "submittedAt": 1567512491587205024,
      "from": "richard@piedpiper.com",
      "replyTo": "gavin@hooli.com",
      "to": "gavin@hooli.com",
      "groups": ["welcome", "user-onboarding"],
      "ipPool": "transactional-piedpiper",
      "headers": {
         "X-Campaign-Id": 113
      },
      "customFields": {
        "Company": "Hooli"
      },
      "subject": "Building great products?",
      "preText": "thanks for the inspiration ...",
      "htmlBody": "<html><body>{{.FirstName}}, I have been following your journey since {{.Company}} days. Just wanted to thank you for inspiring us.</body></html>",
      "textBody": "{{.FirstName}}, I have been following your journey since {{.Company}} days. Just wanted to thank you for inspiring us.",
      "trackOpens": true,
      "trackClicks": true
   }
}

Just to take a step back, when you use SendPost API call to send an email, the email message goes through a complete lifecycle:

• API request will be processed
• Decide to either drop the request if email is either invalid or is in suppression list
• Decide to attempt email delivery
• During email delivery if a hard bounce happens then raise an event. If a soft bounce happens then raise an event alongwith retrying after X time
• If email is delivered successfully then raise a delivered event

Once email delivery has been done a recipient may decide to:

• Open the email message. If open tracking is enabled then opened event is generated
• Click the email message. If click tracking is enabled then clicked event is generated
• Recipient may unsubscribe from receiving future emails in which case unsubscribed event is generated
• And the worst scenario is if they mark your email as spam in which case a spam event is generated

For all the aforementioned events, SendPost can generate a webhook call. The event structure across these call remains same however some fields may remain empty or have data based on event webhook that is raised.

Also as explained earlier, for a single emailMessage multiple events are generated. The emailMessage sent via HTTP Post will remain same across different events during the lifecycle of the email message.

Every event generated as SendPost webhook will have type field in event object:

Below specified are event specific fields. All these fields are contained inside eventMetadata sub-object inside event object. These fields are set for specific webhook events only.

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

1. Get the SMTP username and password from your SendPost account.
2. 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.
3. Set the username and password.
4. 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

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: 'erlich@piedpiper.com',
            to: 'gilfoyle@piedpiper.com',
            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);

<?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('erlich@piedpiper.com', 'Erlich');
    $mail->addAddress('gilfoyle@piedpiper.com', '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}";
}

#!/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 =     'erlich@piedpiper.com'
destination = ['gilfoyle@piedpiper.com']

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)

package main

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

// Sending Email Using Smtp in Golang

func main() {

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

	from := "erlich@piedpiper.com"
	toList := []string{"gilfoyle@piedpiper.com"}
	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")
}

// 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 = "erlich@piedpiper.com";
  static final String FROMNAME = "Erlich Bachman";

  // Replace recipient@example.com with a "To" address. If your account
  // is still in the sandbox, this address must be verified.
  static final String TO = "gilfoyle@piedpiper.com";

  // 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.
  }
}