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:
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"

templateId
string

Template ID for the email template

templateVariables
object

Key-Value pair of template variables

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"