](https://god.gw.postman.com/run-collection/33476323-e6dbd27f-c4a7-4d49-bcac-94b0611b938b?action=collection%2Ffork&source=rip_markdown&collection-url=entityId%3D33476323-e6dbd27f-c4a7-4d49-bcac-94b0611b938b%26entityType%3Dcollection%26workspaceId%3D6b1e4f65-96a9-4136-9512-6266c852517e)
# 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](https://app.sendpost.io/register).
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 **hello@sendpost.io**
* [PHP](https://github.com/sendpost/sendpost_php_sdk)
* [Javascript](https://github.com/sendpost/sendpost_javascript_sdk)
* [Ruby](https://github.com/sendpost/sendpost_ruby_sdk)
* [Python](https://github.com/sendpost/sendpost_python_sdk)
* [Golang](https://github.com/sendpost/sendpost_go_sdk)
# 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
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`
- 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](https://www.ietf.org/rfc/rfc3207.txt).
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
```javascript
"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: "This email was sent with SendPost using the ", "Javamail Package", " for Java." ); 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. servers: - url: https://api.sendpost.io/api/v1 security: [] tags: - name: Email description: > 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. ## Personalisation within email SendPost allows users to personalize email content dynamically using Handlebars. Personalization can be applied to the text body, html body and the subject itself. Here's how you can utilize custom field variables to enhance your email communication. ```js { "from": { "email": "richard@piedpiper.com", "name": "Richard" }, "to": [ { "email": "gavin@hooli.com", "name": "Gavin Belson", "customFields": { "firstName": "Gavin", "discountCode": "BELSON240" "status": "VIP" } }, { "email": "erlich@piedpiper.com", "name": "Erlich Bachman", "customFields": { "firstName": "Erlich", "discountCode" : "BACHMAN10" "status": "Incubator" } }, ], "subject": "Hello, {{firstName}}! Welcome to Pied Piper!", "htmlBody": "
Hi {{firstName}},
Your discount code is {{discountCode}}. Your account status is {{status}}}.
", "textBody": "Hi {{firstName}},\n\nYour discount code is {{discountCode}}. Your account status is {{status}}.", "ippool": "default", "trackOpens": true, "trackClicks": true, "groups": [ "special-offers" ] } ``` ### Explanation: Custom Fields for Personalization: - Each recipient in the to array has a customFields map. - These fields are used to dynamically render the email content. - Example: `{{firstName}}`, `{{discountCode}}`, and `{{status}}` in the subject, htmlBody, and textBody are replaced with the respective values from customFields. ### Output Example: For gavin@hooli.com: Subject: Hello, Gavin! Your Special Offer AwaitsHi Gavin,
Your discount code is BELSON240. Your account status is VIP.
--- For erlich@piedpier.com: Subject: Hello, Erlich! Your Special Offer AwaitsHi Erlich,
Your discount code is BACHMAN10. Your account status is Incubator.
--- ### Note: `unsubscribe` is a reserved custom field name. You can't use it as a custom field name. ## Unsubscribe link in your templates Here is how to add an unsubscribe link to your SendPost email templates. Add this to your email template: ``` Unsubscribe ``` Any user who clicks on this will get added to the suppression list on your SendPost subaccount. - name: Domain description: > 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. - name: Stats description: > 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. - name: Suppression description: > 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. - name: IP description: > This API allows you to manage your ips for a specific account. Across all the requests you need to pass X-Account-ApiKey header. - name: IPPools description: > This API allows you to manage your ippools for a specific account. Across all the requests you need to pass X-Account-ApiKey header. ## Routing Strategies and Metadata ### routing_strategy 0 (RoundRobinStrategy) In RoundRobinStrategy all your emails are fairly shared between all your IPs and TPSPs The payload for routingMetaData for RoundRobinStrategy is: Key | Value --------- | ----------- routingStrategy | 0 routingMetaData | "{}" For example, if you have IP 3.238.19.86 and TPSPs Sendgrid and Mailgun and send 6 emails then 2 emails will be sent from 3.238.19.86, Mailgun and Sengrid. ### routing_strategy 1 (EmailProviderStrategy) In the EmailProviderStrategy we can assign IPs and TPSPs to the specific email provider. Existing email provider types: Id | Description --------- | ----------- 0 | Email provider Gmail 1 | Email provider Yahoo 2 | Email provider AOL 3 | Email provider Microsoft 4 | Email provider Comcast 5 | Email provider Yandex 6 | Email provider GMX 7 | Email provider Mailru 8 | Email provider Icloud 9 | Email provider Zoho 10 | Email provider QQ 11 | Email provider default Key | Value --------- | ----------- routingStrategy | 1 routingMetaData | JSON payload JSON payload example: ```json { "0": "[\"IP_100\",\"IP_105\"]", "1": "[\"TPSP_101\"]", "others": "[\"IP_102\",\"TPSP_103\",\"IP_104\"]" } ``` On the left side, you can see the email types: 0 is Gmail, 1 is Yahoo, and 'others' in this case all email addresses that don't belong to Yahoo or Gmail, the left side key is in the string format. Currently, for the right side, the format is an Array of strings in the format of "Entity_ID". Where 'Entity' could be 'IP' or 'TPSP' (third-party sending provider). For example, the 'IP_' prefix means that the entity is IP, and 100 in "IP_100" mean that the ID of this IP is 100. For example, the 'TPSP_' prefix means that the entity is TPSP, and 101 in "TPSP_101" mean that the ID of this TPSP is 101. The metadata above means: that for Gmail we send emails fairly between IPs with ID 105 and ID 100; and for Yahoo, we send emails from TPSP with ID 101; and for all the rest email types we send fairly from the TPSP with ID 103 and from IP with ID 104 and 102. ### routing_strategy 2 (VolumePercentageStrategy) In the VolumePercentageStrategy we can assign volumes to the specific IPs and TPSPs. Key | Value --------- | ----------- routingStrategy | 2 routingMetaData | JSON payload JSON payload example: ```json { "IP_100": "2", "IP_101": "3", "TPSP_102": "1", "TPSP_103": "4" } ``` Currently, for the left side, the format is a string in the format of "Entity_ID". Where 'Entity' could be 'IP' or 'TPSP' (third-party sending provider). And for the right side, the volume number of emails that we send (also in the string format). For example, the 'IP_' prefix means that the entity is IP, and 100 in "IP_100" mean that the ID of this IP is 100. For example, the 'TPSP_' prefix means that the entity is TPSP, and 101 in "TPSP_101" mean that the ID of this TPSP is 101. The metadata above means: that, for example, if we send 20 emails, 4 go from IP with ID 100, 6 go from IP with ID 101, 2 go from TPSP with ID 102, and 8 go from TPSP with ID 103. ### routing_strategy 3 (SendingDomainStrategy) In the SendingDomainStrategy we can assign IPs and TPSPs to the specific domains that we are sending from. Key | Value --------- | ----------- routingStrategy | 3 routingMetaData | JSON payload JSON payload example: ```json { "sendx.io": "[\"TPSP_100\",\"IP_105\"]", "sendpost.io": "[\"IP_101\"]", "others": "[\"IP_102\",\"IP_103\",\"TPSP_104\"]" } ``` On the left side, you can see the domains, in this case, it's sendx.io and sendpost.io, and 'others'. The email would be put in the 'others' category if its domain doesn't belong to sendx.io or sendpost.io. Currently, for the right side, the format is an Array of strings in the format of "Entity_ID". Where 'Entity' could be 'IP' or 'TPSP' (third-party sending provider). For example, the 'IP_' prefix means that the entity is IP, and 100 in "IP_100" mean that the ID of this IP is 100. For example, the 'TPSP_' prefix means that the entity is TPSP, and 101 in "TPSP_101" mean that the ID of this TPSP is 101. The metadata above means: that, for example, if we send emails from t1@sendx.io, t2@sendx.io, t1@sendpost.io, t1@gmail.com, t2@gmail.com, t3@gmail.com, t4@yahoo.com The sendx.io emails (t1@sendx.io, t2@sendx.io) will be sent from TPSP with ID 100 and IP with ID 105. The sendpost.io emails will be sent from IP with ID 101. The 'others' emails (t1@gmail.com, t2@gmail.com, t3@gmail.com, t4@yahoo.com) will be sent from IP with ID 102 and 103, and TPSP with ID 104. - name: Stats (A) description: > 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. - name: Sub-Account description: > This API allows you to manage your sub-accounts for a specific sub-account. Across all the requests you need to pass X-Account-ApiKey header. - name: Webhook description: > This API allows you to manage your webhooks for a specific account. Across all the requests you need to pass X-Account-ApiKey header. - name: Webhook Reference description: > Webhooks are an 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 unsubscribed 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 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](https://requestbin.com/) 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. - name: Message description: > This API allows you to manage your messages for a specific account. Across all the requests you need to pass X-Account-ApiKey header. paths: /account/webhook/{webhook_id}: get: tags: - Webhook summary: Get Webhook description: Retrieves a specific webhook based on its ID. operationId: getWebhook parameters: - name: webhook_id in: path required: true description: The ID of the webhook to retrieve. schema: type: integer example: 117 responses: '200': description: Webhook details. content: application/json: schema: $ref: '#/components/schemas/Webhook' security: - accountAuth: [] components: schemas: Webhook: type: object additionalProperties: true properties: id: type: integer description: Unique ID for the webhook. example: 117 enabled: type: boolean description: Indicates if the webhook is active or paused. example: true url: type: string description: URL endpoint to which webhook calls need to be made. example: https://app.hooli.com/email/webhook processed: type: boolean description: Trigger webhook on email message being processed. example: true delivered: type: boolean description: Trigger webhook on email message being delivered. example: true dropped: type: boolean description: Trigger webhook on email message being dropped. example: false softBounced: type: boolean description: Trigger webhook on email message being soft bounced. example: false hardBounced: type: boolean description: Trigger webhook on email message being hard bounced. example: true opened: type: boolean description: Trigger webhook on email message being opened. example: true clicked: type: boolean description: Trigger webhook on email message link being clicked. example: true unsubscribed: type: boolean description: Trigger webhook on email message being unsubscribed. example: true spam: type: boolean description: Trigger webhook on email message being marked as spam. example: true sent: type: boolean description: Trigger webhook on email message being sent. example: true smtpDropped: type: boolean description: Trigger webhook on email message being dropped by SMTP. example: false uniqueOpen: type: boolean description: Trigger webhook on unique email opens. example: true uniqueClick: type: boolean description: Trigger webhook on unique email clicks. example: true created: type: integer format: int64 description: UNIX epoch nano timestamp when the webhook was created. example: 1567512491588004000 created_by: $ref: '#/components/schemas/Member' type: object description: Member who created the webhook nullable: true updated_by: $ref: '#/components/schemas/Member' type: object description: Member who updated the webhook nullable: true Member: type: object properties: id: type: integer description: Unique ID for the member example: 117 isVerified: type: boolean description: Indicates whether the member is verified example: true isForbidden: type: boolean description: Indicates whether the member is forbidden example: false firebaseUID: type: string description: Firebase UID for the member example: '1234567890' email: type: string description: Email for the member example: raj@piedpiper.com name: type: string description: Name for the member example: Raj url: type: string description: Logo URL for the member example: https://www.sendpost.io/logo.png companyName: type: string description: Company name for the member example: SendPost onboardQAnswered: type: boolean description: Indicates whether the member has answered onboarding question example: true phoneNumber: type: string description: Phone number for the member example: '+919876543210' notesColor: type: string description: Color for the member's notes example: '#000000' created: type: integer description: UNIX epoch nano timestamp when the member was created example: 1567512491588004000 securitySchemes: accountAuth: type: apiKey in: header name: X-Account-ApiKey description: This api key can be used for all account level operations ````