Skip to main content
POST
JavaScript

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

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:
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. Overrides the default webhook configured at the account level. Useful for per-email or per-customer webhook routing.

Example:

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

Response

200 - application/json

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. Common codes:

  • 0: Success (no error)
  • 1: Invalid recipient email
  • 2: Recipient in suppression list
  • 3: Domain not verified
  • 4: Rate limit exceeded
  • 5: Invalid sender email
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"