Skip to main content
POST
JavaSript

Authorizations

X-SubAccount-ApiKey
string
header
required

This api key can be used only for sub account level operations

Body

application/json

Email message details with template information

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.

from
object
required

The sender's email address and optional display name

Example:
to
object[]
required

List of recipients. Each recipient can have their own CC, BCC, and custom fields for personalization. Maximum 1000 recipients per API call.

Required array length: 1 - 1000 elements
replyTo
object

The reply-to email address. If not specified, replies will go to the from address

Example:
tpspFrom
object

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.
Example:
subject
string

Email subject line. Supports Handlebars templating for personalization. Example: "Hello, {{firstName}}! Your order is ready"

Maximum string length: 998
Example:

"Welcome to SendPost, {{firstName}}!"

preText
string

Preview text (preheader) shown in email clients before opening the email. This text appears after the subject line in most email clients' inbox view.

Maximum string length: 200
Example:

"Your weekly digest is here with 5 new updates..."

htmlBody
string

HTML content of the email. Supports Handlebars templating for personalization. Use {{customFieldName}} to insert recipient-specific values.

Example:

"<html><body><h1>Hello {{firstName}}</h1><p>Welcome to our platform!</p></body></html>"

textBody
string

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}},\n\nWelcome to our platform!\n\nBest regards,\nThe Team"

ampBody
string

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:

"<!doctype html><html ⚡4email><head>...</head><body>...</body></html>"

template
string

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
string

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
object

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.

Example:
trackOpens
boolean
default:true

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)

Example:

true

trackClicks
boolean
default:true

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)

Example:

true

groups
string[]

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).

Example:
attachments
object[]

File attachments to include with the email. Maximum total attachment size: 25MB. Supported formats: PDF, images, documents, etc.

webhookEndpoint
string<uri>

Custom webhook URL to receive events for this specific email. It receives every event of the email except Validation, in addition to your account webhooks; it doesn't replace them. Requests to it are signed only when the URL exactly matches an account webhook that has a secret. See Webhook Signature Verification. Useful for per-email or per-customer webhook routing.

Example:

"https://your-app.com/webhooks/email-events"

skipValidation
boolean
default:false

Skip the real-time list cleaning check for this email. Only matters when the sub-account has the Real-Time List Cleaning add-on: the email is then sent without a check and no Validation webhook event (type 82) is sent for it. It can only turn the check off, never on.

The header X-Sendpost-Validate: false in headers does the same, including over SMTP relay. See Real-Time Validation Results.

Example:

false

templateId
string

Template ID for the email template

templateVariables
object

Key-Value pair of template variables

Response

A list of email message response objects.

to
string

The recipient email address this response corresponds to

Example:

"customer@example.com"

submittedAt
integer<int64>

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
string

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
integer

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
string

Human-readable message describing the result. On success: "Email submitted successfully" On error: Description of what went wrong

Example:

"Email submitted successfully"