";
// 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"),
"SendPost SMTP Test
",
"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.
# API Contract Versioning (Public REST)
The public REST API uses a versioned response contract so field changes stay
non-breaking:
* Send `X-SendPost-Public-Contract: v1` to opt into the current v1 response
shape, or `legacy` for the pre-v1 shape. If the header is omitted, the
applied contract is policy-driven β `legacy` before the published sunset
date, `v1` after it.
* Every response echoes `X-SendPost-Public-Contract: `. When the
`legacy` contract is served, responses also include `Deprecation: true`,
`Sunset: `, and `Link: ; rel="deprecation"`.
* Migrate to `v1` before the sunset date. Notable legacy β v1 field changes:
Suppression `smtp_error` β `smtpError`, Stat `email_type` β `emailType`.
> `X-SendPost-Private-Api: true` is an internal header used only by the
SendPost dashboard to receive richer internal objects. It is not part of the
public SDK contract and should not be set by API integrations.
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 Awaits
Hi Gavin,
Your discount code is BELSON240. Your account
status is VIP.
---
For erlich@piedpier.com:
Subject: Hello, Erlich! Your Special Offer Awaits
Hi 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:
/subaccount/email/:
post:
tags:
- Email
summary: Send Email
description: >
Send transactional or marketing emails to one or multiple recipients.
This is the primary endpoint for all email sending through SendPost.
**Capabilities:**
- **Single Email**: Send to one recipient with full personalization
- **Batch Sending**: Send to up to 500 recipients in a single API call
- **Personalization**: Use Handlebars templating (`{{variableName}}`) in
subject, HTML body, and text body
- **Attachments**: Include base64-encoded files (max 25MB total per
request)
- **Tracking**: Enable/disable open and click tracking per email
- **IP Pool Routing**: Route emails through specific IP pools
**Common Use Cases:**
| Use Case | Example |
|----------|---------|
| Order Confirmation | Send receipt with order details after purchase |
| Password Reset | Time-sensitive security email with reset link |
| Welcome Email | Onboard new users with personalized greeting |
| Shipping Notification | Update customers when orders ship |
| Invoice/Receipt | Attach PDF invoices to billing emails |
**Personalization Example:**
```json
{
"to": [{
"email": "john@example.com",
"customFields": {
"firstName": "John",
"orderTotal": "$99.99"
}
}],
"subject": "Hi {{firstName}}, your order is confirmed!",
"htmlBody": "Thanks {{firstName}}! Your total: {{orderTotal}}
"
}
```
**Test Email Addresses:**
SendPost provides special test email addresses for testing webhooks and
events without sending real emails:
| Test Email | Behavior |
|------------|----------|
| `test@playwithsendpost.io` | Generates delivered event, then simulates
opens and clicks after a few seconds |
| `deliver@playwithsendpost.io` | Generates delivered event only (no
opens/clicks) |
| `hardbounce@playwithsendpost.io` | Always generates a hard bounce
event |
| `softbounce@playwithsendpost.io` | Always generates a soft bounce
event |
| `dropped@playwithsendpost.io` | Always generates a dropped event
(SMTPDropped) |
**Self-Test Email (Send to Yourself):**
Use `hello@playwithsendpost.io` as the **from** address to send emails
to yourself for testing:
- **Sender**: Must be `hello@playwithsendpost.io`
- **Recipient**: Must be your account owner email (the email you used to
sign up)
- **Behavior**: Real email delivery to your inbox (no domain
verification required, no mock mode)
- **Use Case**: Test your API integration by sending real emails to
yourself without domain setup
**Example:**
```json
{
"from": {"email": "hello@playwithsendpost.io"},
"to": [{"email": "your-account-email@example.com"}],
"subject": "Test Email to Myself",
"htmlBody": "This is a test email to myself
"
}
```
This will send a real email to your inbox that you can actually receive
and open.
**Note**: If you send to any email other than your account email, the
request will be rejected with an error.
**Using Test Emails:**
- Simply send to any test email address like a normal recipient
- Mock mode is automatically enabled for test emails
- All events trigger webhooks normally
- Events are marked as mock messages but follow the same structure as
real events
- Perfect for testing webhook integrations without using real email
addresses
**Example:**
```json
{
"to": [{"email": "test@playwithsendpost.io"}],
"from": {"email": "sender@example.com"},
"subject": "Test Email",
"htmlBody": "This is a test
"
}
```
This will generate: Sent β Delivered β Opened (after 2-5s) β Clicked
(after 1-3s more)
**Response:** Returns an array of responses, one per recipient, each
containing:
- `messageId` - Unique ID for tracking
- `submittedAt` - Timestamp of acceptance
- `errorCode` and `message` - Status information
operationId: sendEmail
requestBody:
description: Email message details
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EmailMessageObject'
responses:
'200':
description: A list of email message response objects.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/EmailResponse'
'400':
description: >
The request was rejected before any email was sent. The body is a
single `EmailResponse` object, not an array. `errorCode` is 3 or 4
when the `from` domain doesn't exist or isn't verified, and 11 when
`tpspFrom` is invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/EmailResponse'
example:
to: ''
submittedAt: 1704067200000000000
messageId: ''
errorCode: 11
message: >-
tpspFrom email must be on the same registered domain as from
email
security:
- subAccountAuth: []
x-code-samples:
- lang: js
label: JavaScript
source: |
const { EmailApi, EmailMessage } = require('sendpost_js');
const email = new EmailApi();
const apiKey = 'your_api_key'; // {String} Sub-Account API Key
(async function() {
const message = new EmailMessage();
message.from = { email: 'richard@piedpiper.com' };
message.to = [{ email: 'gavin@hooli.com' }]
message.subject = 'Hello'
message.htmlBody = 'it works!';
message.ippool = 'PiedPiper'
const opts = {
emailMessage: message
};
try {
const data = await email.sendEmail(apiKey, opts)
console.log('API called successfully. Returned data: ', data);
} catch (error) {
console.error(error);
}
})()
- lang: php
label: PHP
source: >
require_once(__DIR__ . '/vendor/autoload.php');
$client = new GuzzleHttp\Client();
$apiInstance = new sendpost\api\EmailApi($client);
$x_sub_account_api_key = 'your_api_key'; // string | Sub-Account API
Key
$email_message = new \sendpost\model\EmailMessage();
$email_message->setSubject('Hello World');
$email_message->setHtmlBody('it works!');
$email_message->setIppool('PiedPiper');
$from = new \sendpost\model\From();
$from->setEmail('richard@piedpiper.com');
$to = new \sendpost\model\To();
$to->setEmail('gavin@hooli.com');
$email_message->setTo(array($to));
$email_message->setFrom($from);
try {
$result = $apiInstance->sendEmail($x_sub_account_api_key, $email_message);
print_r($result);
} catch (Exception $e) {
echo 'Exception when calling EmailApi->sendEmail: ', $e->getMessage(), PHP_EOL;
}
- lang: python
label: Python
source: |
import sendpost_python_sdk
from pprint import pprint
from sendpost_python_sdk.apis.tags import email_api
# Enter a context with an instance of the API client
with sendpost_python_sdk.ApiClient() as api_client:
# Create an instance of the API class
api_instance = email_api.EmailApi(api_client)
x_sub_account_api_key = "your_api_key" # str | Sub-Account API Key
email = {
"from": {
"email": "richard@piedpiper.com",
},
"to": [
{
"email": "gavin@hooli.com",
}
],
"subject": "Hello World",
"htmlBody": "it works!",
"ippool": "PiedPiper",
}
try:
api_response = api_instance.send_email(header_params={ 'X-SubAccount-ApiKey': x_sub_account_api_key}, body=email)
pprint(api_response)
except sendpost_python_sdk.ApiException as e:
print("Exception when calling EmailApi->send_email: %s\n" % e)
- lang: ruby
label: Ruby
source: >
require 'sendpost_ruby_sdk'
api_instance = Sendpost::EmailApi.new
x_sub_account_api_key = 'your_api_key' # String | Sub-Account API
Key
email_message = Sendpost::EmailMessage.new
email_message.from = {
email: 'richard@piedpiper.com'
}
email_message.to = [{
email: 'gavin@hooli.com'
}]
email_message.subject = 'Hello World'
email_message.html_body = 'it works!'
email_message.ippool = 'PiedPiper'
opts = {
email_message: email_message # EmailMessage | Email message
}
begin
result = api_instance.send_email(x_sub_account_api_key, opts)
p result
rescue Sendpost::ApiError => e
puts "Exception when calling EmailApi->send_email: #{e}"
end
- lang: go
label: Go
source: |
cfg := sendpost.NewConfiguration()
client := sendpost.NewAPIClient(cfg)
emailMessage := sendpost.EmailMessage{}
emailMessage.SetSubject("Hello World")
emailMessage.SetHtmlBody("it works!")
emailMessage.SetIppool("PiedPiper")
emailMessage.From = &sendpost.From{}
emailMessage.From.SetEmail("richard@piedpiper.com")
tos := make([]sendpost.To, 0)
to := &sendpost.To{}
to.SetEmail("gavin@hooli.com")
tos = append(tos, *to)
emailMessage.To = tos
emailRequest := sendpost.ApiSendEmailRequest{}
emailRequest = emailRequest.XSubAccountApiKey("your_api_key")
emailRequest = emailRequest.EmailMessage(emailMessage)
res, _, err := client.EmailApi.SendEmailExecute(emailRequest)
- lang: shell
label: cURL
source: |
curl -X POST "https://api.sendpost.io/api/v1/subaccount/email/" \
-H "accept: application/json" \
-H "X-SubAccount-ApiKey: your_api_key" \
-d '{
"from": { "email": "richard@piedpiper.com" },
"to": [{ "email": "gavin@hooli.com" }],
"subject": "Hello World",
"htmlBody": "it works!",
"ippool": "PiedPiper"
}'
components:
schemas:
EmailMessageObject:
type: object
description: >
Email message object containing all the details required to send an
email.
At minimum, you need to provide `from`, `to`, and either `subject` with
`htmlBody`/`textBody` or a `template`.
required:
- from
- to
properties:
from:
$ref: '#/components/schemas/EmailAddress'
description: The sender's email address and optional display name
replyTo:
$ref: '#/components/schemas/EmailAddress'
description: >-
The reply-to email address. If not specified, replies will go to the
`from` address
tpspFrom:
$ref: '#/components/schemas/EmailAddress'
description: >
Optional sender for emails delivered through a third-party sending
provider (TPSP): SendGrid, Amazon SES, Mailgun, SparkPost, Postmark,
or Custom SMTP. For example, when sending over your SendPost warmup
cap overflows to a TPSP pool, those emails go out as `tpspFrom`
instead of `from`.
- Must be on the same registered domain as `from`. For example,
`from` on `agent1.example.com` and `tpspFrom` on
`agent2.example.com`.
- It doesn't need to be verified in SendPost, but it must be set up
as a sender at the TPSP.
- Emails delivered on SendPost IPs still go out as `from`. Stats and
webhook events are always reported under `from`.
- If `name` is omitted, the `from` name is used. If `replyTo` isn't
set, replies go to `tpspFrom`.
- If `tpspFrom` is invalid, the whole request is rejected with HTTP
400 and `errorCode` 11.
to:
type: array
description: >
List of recipients. Each recipient can have their own CC, BCC, and
custom fields for personalization.
Maximum 1000 recipients per API call.
items:
$ref: '#/components/schemas/Recipient'
minItems: 1
maxItems: 1000
subject:
type: string
description: >
Email subject line. Supports Handlebars templating for
personalization.
Example: "Hello, {{firstName}}! Your order is ready"
example: Welcome to SendPost, {{firstName}}!
maxLength: 998
preText:
type: string
description: >
Preview text (preheader) shown in email clients before opening the
email.
This text appears after the subject line in most email clients'
inbox view.
example: Your weekly digest is here with 5 new updates...
maxLength: 200
htmlBody:
type: string
description: >
HTML content of the email. Supports Handlebars templating for
personalization.
Use {{customFieldName}} to insert recipient-specific values.
example: >-
Hello {{firstName}}
Welcome to our
platform!
textBody:
type: string
description: >
Plain text content of the email. Used as fallback when HTML cannot
be rendered.
Also improves deliverability as some spam filters prefer multipart
emails.
example: |-
Hello {{firstName}},
Welcome to our platform!
Best regards,
The Team
ampBody:
type: string
description: >
AMP HTML content for supported email clients (Gmail, Yahoo).
Enables interactive email experiences like carousels, forms, and
real-time content.
See https://amp.dev/about/email/ for more details.
example: ......
template:
type: string
description: >
Name of a pre-defined template to use for this email.
When specified, the template's subject, htmlBody, and textBody will
be used
unless explicitly overridden in this request.
example: welcome-email-v2
ippool:
type: string
description: >
Name of the IP pool to use for sending this email.
If not specified, the default IP pool for the sub-account will be
used.
example: transactional
headers:
type: object
description: >
Custom email headers to include in the message.
Common uses: adding List-Unsubscribe headers, custom tracking IDs,
or priority flags.
Note: Some headers like From, To, Subject are set automatically and
cannot be overridden.
additionalProperties:
type: string
example:
X-Custom-Header: custom-value
X-Campaign-ID: summer-sale-2024
List-Unsubscribe:
trackOpens:
type: boolean
description: >
Whether to track email opens using a tracking pixel.
When enabled, a 1x1 transparent image is inserted into the HTML
body.
Default: true (if not specified)
default: true
example: true
trackClicks:
type: boolean
description: >
Whether to track link clicks by rewriting URLs through SendPost's
tracking domain.
When enabled, all links in htmlBody are replaced with tracking URLs.
Default: true (if not specified)
default: true
example: true
groups:
type: array
description: >
Tags/groups to categorize this email for analytics and reporting.
Use groups to segment your email statistics (e.g., by campaign,
email type, or customer segment).
items:
type: string
example:
- transactional
- order-confirmation
- premium-customers
attachments:
type: array
description: |
File attachments to include with the email.
Maximum total attachment size: 25MB.
Supported formats: PDF, images, documents, etc.
items:
$ref: '#/components/schemas/Attachment'
webhookEndpoint:
type: string
description: |
Custom webhook URL to receive events for this specific email.
Overrides the default webhook configured at the account level.
Useful for per-email or per-customer webhook routing.
format: uri
example: https://your-app.com/webhooks/email-events
example:
from:
email: notifications@yourcompany.com
name: Your Company
replyTo:
email: support@yourcompany.com
name: Support Team
to:
- email: customer@example.com
name: John Doe
customFields:
firstName: John
orderId: ORD-12345
orderTotal: $99.99
subject: Your order {{orderId}} has been shipped!
htmlBody: >-
Hi {{firstName}}
Your order {{orderId}} worth
{{orderTotal}} is on its way!
textBody: >-
Hi {{firstName}}, Your order {{orderId}} worth {{orderTotal}} is on
its way!
ippool: transactional
trackOpens: true
trackClicks: true
groups:
- order-shipped
- transactional
EmailResponse:
type: object
description: >
Response object returned for each recipient when sending an email.
Contains the message ID for tracking and any error information if the
submission failed.
properties:
to:
type: string
description: The recipient email address this response corresponds to
example: customer@example.com
submittedAt:
type: integer
format: int64
description: >
UNIX epoch timestamp in nanoseconds when the email was accepted for
processing.
Use this for precise timing and correlation with webhook events.
example: 1704067200000000000
messageId:
type: string
description: >
Unique identifier (UUID) for this email message.
Use this ID to track the email through webhooks and the message
lookup API.
example: 550e8400-e29b-41d4-a716-446655440000
errorCode:
type: integer
description: |
Error code if the email submission failed:
- 0: Success (no error)
- 1: Invalid recipient email
- 2: Recipient in suppression list
- 3: `from` domain doesn't exist in this sub-account
- 4: `from` domain isn't verified
- 5: IP pool doesn't exist
- 6: Template doesn't exist
- 7: Empty template name
- 8: Internal error (message ID generation)
- 9: Internal error (message storage)
- 10: Invalid attachment
- 11: Invalid `tpspFrom`
example: 0
message:
type: string
description: |
Human-readable message describing the result.
On success: "Email submitted successfully"
On error: Description of what went wrong
example: Email submitted successfully
example:
to: customer@example.com
submittedAt: 1704067200000000000
messageId: 550e8400-e29b-41d4-a716-446655440000
errorCode: 0
message: Email submitted successfully
EmailAddress:
type: object
description: An email address with an optional display name
required:
- email
properties:
email:
type: string
format: email
description: The email address (must be a valid email format)
example: sender@example.com
name:
type: string
description: |
Display name shown in email clients.
Will appear as "Name " in the From/To fields.
example: John Doe
maxLength: 256
example:
email: sender@example.com
name: John Doe
Recipient:
type: object
description: >
A recipient of the email with optional CC, BCC, and custom fields for
personalization.
Each recipient receives their own copy of the email with their specific
custom field values.
required:
- email
properties:
email:
type: string
format: email
description: The recipient's email address
example: recipient@example.com
name:
type: string
description: The recipient's display name
example: Jane Smith
maxLength: 256
cc:
type: array
description: |
Carbon copy recipients for this specific recipient's email.
CC addresses will be visible to all recipients of this email copy.
items:
$ref: '#/components/schemas/CopyTo'
maxItems: 50
bcc:
type: array
description: |
Blind carbon copy recipients for this specific recipient's email.
BCC addresses are hidden from all other recipients.
items:
$ref: '#/components/schemas/CopyTo'
maxItems: 50
customFields:
type: object
additionalProperties: true
description: >
Custom fields for personalizing the email content for this
recipient.
Use Handlebars syntax ({{fieldName}}) in subject, htmlBody, or
textBody to insert values.
Reserved field names: `unsubscribe` (auto-generated unsubscribe
link).
example:
firstName: Jane
lastName: Smith
accountId: ACC-12345
planName: Premium
example:
email: jane@example.com
name: Jane Smith
cc:
- email: manager@example.com
name: Manager
customFields:
firstName: Jane
companyName: Acme Corp
Attachment:
type: object
description: >
A file attachment for the email.
The content must be Base64 encoded. Maximum total attachment size per
email is 25MB.
required:
- content
- filename
properties:
content:
type: string
format: byte
description: |
Base64 encoded content of the attachment file.
Ensure proper encoding to avoid corruption.
example: SGVsbG8gV29ybGQh
filename:
type: string
description: |
Name of the attachment file as it will appear to recipients.
Include the file extension (e.g., "report.pdf", "image.png").
example: invoice-12345.pdf
maxLength: 255
example:
filename: monthly-report.pdf
content: JVBERi0xLjQKJeLjz9MKMyAwIG9...
CopyTo:
type: object
description: A CC or BCC recipient with optional custom fields
required:
- email
properties:
email:
type: string
format: email
description: The CC/BCC recipient's email address
example: cc@example.com
name:
type: string
description: The CC/BCC recipient's display name
example: Copy Recipient
maxLength: 256
customFields:
type: object
additionalProperties: true
description: |
Custom fields specific to this CC/BCC recipient.
Allows personalization in CC/BCC copies of the email.
example:
role: Manager
example:
email: cc@example.com
name: Copy Recipient
securitySchemes:
subAccountAuth:
type: apiKey
in: header
name: X-SubAccount-ApiKey
description: This api key can be used only for sub account level operations
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.
](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: