Transactional email sending, delivery and bounce tracking, unsubscribe management and sender-domain identity.
openapi: 3.1.2
info:
title: SendPulse SMTP API
description: >
The SendPulse SMTP API allows you to send transactional emails, manage
unsubscribed users, monitor bounces, and configure sender identities. SMTP
is ideal for high-volume transactional messages like order confirmations,
password resets, and notifications.
version: 1.0.0
x-ai-description: >
Expert-level SMTP relay service for transactional and bulk email delivery.
This API provides granular control over the delivery lifecycle, including
sender IP management, bounce tracking, and multi-channel fallback support.
license:
name: Apache 2.0
identifier: Apache-2.0
servers:
- url: https://api.sendpulse.com
paths:
/smtp/emails:
post:
summary: Send an email
operationId: sendSmtpEmail
tags:
- Emails
x-ai-role: email_deliverability_expert
x-ai-description: >
Triggers the delivery of a transactional email using either custom
HTML/text or a pre-defined system template. This is the primary
endpoint for high-priority communications.
x-ai-reasoning-instructions:
- >-
Determine if the user is providing raw HTML/text or using a template
ID.
- >-
If using attachments, ensure the file size is within limits and
contents are Base64 encoded if using `attachments_binary`.
- >-
Validate that the sender email is already verified in the SendPulse
account.
x-ai-responding-instructions:
- Confirm successful queuing by returning the internal Message ID.
- If a template is used, mention that variables were mapped correctly.
- Advise on checking delivery status via the `id` returned.
x-ai-suggestions:
- Use `template` for consistent branding across transactional emails.
- 'Set `auto_plain_text: true` if you only provide HTML.'
x-ai-capabilities:
confirmation:
type: None
security_info:
data_handling:
- PIIHandling
- ResourceStateUpdate
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- email
properties:
email:
type: object
required:
- subject
- from
- to
oneOf:
- required:
- html
- text
- required:
- template
properties:
html:
type: string
description: HTML version of an email, encoded in Base64
text:
type: string
description: Text version of the email
template:
type: object
required:
- id
- variables
properties:
id:
oneOf:
- type: string
- type: integer
description: Template ID
variables:
type: object
description: Template variables mapping
auto_plain_text:
type: boolean
default: false
subject:
type: string
from:
type: object
required:
- name
- email
properties:
name:
type: string
email:
type: string
to:
type: array
items:
type: object
required:
- email
properties:
name:
type: string
email:
type: string
reply_to:
type: object
properties:
name:
type: string
email:
type: string
cc:
type: array
items:
type: object
properties:
name:
type: string
email:
type: string
bcc:
type: array
items:
type: object
properties:
name:
type: string
email:
type: string
attachments:
type: object
description: Filename to content mapping
attachments_binary:
type: object
description: Filename to Base64 content mapping
responses:
'200':
description: Email sent successfully
content:
application/json:
schema:
type: object
properties:
result:
type: boolean
id:
type: string
example: pzkic9-0afezp-fc
'401':
description: Unauthorized
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
account.expired:
summary: account.expired
value:
message: Account expired
error_code: 403
'422':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
email.required:
summary: email.required
value:
message: Argument email missing
error_code: 422
from.email.required:
summary: from.email.required
value:
message: Argument from.email missing
error_code: 10
from.email.invalid:
summary: from.email.invalid
value:
message: Argument from.email is invalid
error_code: 10
email.to.invalid:
summary: email.to.invalid
value:
message: Argument email.to is invalid
error_code: 11
subject.required:
summary: subject.required
value:
message: Argument subject missing
error_code: 12
email.body.missing:
summary: email.body.missing
value:
message: Missed email body
error_code: 13
template.id.required:
summary: template.id.required
value:
message: Argument template.id missing
error_code: 10
template.invalid:
summary: template.invalid
value:
message: Argument template is invalid
error_code: 422
from.invalid:
summary: from.invalid
value:
message: Argument from is invalid
error_code: 422
attachments_binary.invalid:
summary: attachments_binary.invalid
value:
message: Argument attachments_binary is invalid
error_code: 422
recipients.too_many:
summary: recipients.too_many
value:
message: 5.5.3 Too many recipients
error_code: 550
data.malformed:
summary: data.malformed
value:
message: Badly formed incoming data
error_code: 999
recipient.email.invalid:
summary: recipient.email.invalid
value:
message: Recipient email is invalid
error_code: 422
template.not_found:
summary: template.not_found
value:
message: Template not found
error_code: 31
template.body.empty:
summary: template.body.empty
value:
message: Template body is empty
error_code: 32
variables.format_invalid:
summary: variables.format_invalid
value:
message: Variables list passed in wrong format
error_code: 731
smtp_user.not_found:
summary: smtp_user.not_found
value:
message: No such SMTP user, you need to create SMTP account first
error_code: 400
message.size_exceeded:
summary: message.size_exceeded
value:
message: Message size limit exceeded
error_code: 422
sending.limited:
summary: sending.limited
value:
message: >-
Sending from your account is currently limited. Please try
later.
error_code: 422
quota.exceeded:
summary: quota.exceeded
value:
message: Sending quota or bandwidth exceeded
error_code: 422
sender.invalid:
summary: sender.invalid
value:
message: Sender is not valid
error_code: 422
get:
summary: Get a list of emails
operationId: getSmtpEmails
tags:
- Emails
x-ai-role: marketing_automation_specialist
x-ai-description: >
Retrieves historical delivery data for sent emails. Useful for auditing
campaign performance and debugging delivery issues for specific
recipients.
x-ai-reasoning-instructions:
- Apply date filters (`from`, `to`) to narrow down the search window.
- Use pagination (`limit`, `offset`) for large datasets.
x-ai-responding-instructions:
- Summarize the delivery status of the retrieved emails.
- Highlight any 'Bad recipients' or bounce codes if present.
x-ai-suggestions:
- Filter by `recipient` to troubleshoot specific user complaints.
x-ai-capabilities:
confirmation:
type: None
parameters:
- name: limit
in: query
schema:
type: integer
- name: offset
in: query
schema:
type: integer
- name: from
in: query
schema:
type: string
format: date
- name: to
in: query
schema:
type: string
format: date
- name: sender
in: query
schema:
type: string
- name: recipient
in: query
schema:
type: string
- name: country
in: query
schema:
type: string
responses:
'200':
description: List of emails
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/EmailRecord'
'401':
description: Unauthorized
'403':
description: Forbidden
'422':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
tariff.not_allowed:
summary: tariff.not_allowed
value:
message: Your tariff does not allow the operation
error_code: 422
/smtp/emails/total:
get:
summary: Get total amount of sent emails
operationId: getSmtpEmailsTotal
tags:
- Emails
x-ai-role: compliance_officer
x-ai-description: >
Returns the cumulative count of all emails sent through the SMTP
service. Critical for billing reconciliation and volume monitoring.
x-ai-reasoning-instructions:
- >-
Check if this matches the expected volume for the current billing
cycle.
x-ai-responding-instructions:
- State the total number of emails sent to date.
x-ai-suggestions:
- Monitor this periodically to detect unusual spikes in traffic.
x-ai-capabilities:
confirmation:
type: None
responses:
'200':
description: Total count
content:
application/json:
schema:
type: object
properties:
total:
type: integer
'401':
description: Unauthorized
'403':
description: Forbidden
'422':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
smtp_user.not_found:
summary: smtp_user.not_found
value:
message: No such SMTP user, you need to create SMTP account first
error_code: 400
tariff.not_allowed:
summary: tariff.not_allowed
value:
message: Your tariff does not allow the operation
error_code: 422
/smtp/emails/{id}:
get:
summary: Get information about a specific email
operationId: getSmtpEmailInfo
tags:
- Emails
parameters: []
x-ai-role: email_deliverability_expert
x-ai-description: >
Provides detailed delivery and tracking metadata for a single email
transaction, including SMTP response codes and client interaction
details.
x-ai-reasoning-instructions:
- Look for `smtp_answer_code` to identify specific delivery failures.
- >-
Analyze `tracking` data to see if the recipient opened or clicked
links.
x-ai-responding-instructions:
- Detail the exact delivery time and the SMTP server's response.
- Summarize open and click events if tracking was enabled.
x-ai-suggestions:
- >-
If `smtp_answer_code` is 5xx, advise the user to check the recipient
status.
x-ai-capabilities:
confirmation:
type: None
responses:
'200':
description: Detailed email information
content:
application/json:
schema:
$ref: '#/components/schemas/EmailRecord'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
email.not_found:
summary: email.not_found
value:
message: No such email
error_code: 14
'401':
description: Unauthorized
'403':
description: Forbidden
parameters:
- name: id
in: path
required: true
schema:
type: string
/smtp/emails/info:
post:
summary: Get information for a list of emails
operationId: getSmtpEmailsBatchInfo
tags:
- Emails
x-ai-role: marketing_automation_specialist
x-ai-description: >
Batch retrieval of delivery status for up to 500 messages at once.
Highly efficient for large-scale synchronization of delivery states.
x-ai-reasoning-instructions:
- Ensure the input array does not exceed 500 IDs.
x-ai-responding-instructions:
- Summarize the findings for the provided IDs.
x-ai-suggestions:
- Use this for bulk updates of internal delivery dashboards.
x-ai-capabilities:
confirmation:
type: None
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- emails
properties:
emails:
type: array
items:
type: string
maxItems: 500
responses:
'200':
description: List of email records
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/EmailRecord'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
emails.invalid:
summary: emails.invalid
value:
message: Emails param empty or incorrect
error_code: 832
emails.not_found:
summary: emails.not_found
value:
message: No such emails
error_code: 14
'401':
description: Unauthorized
'403':
description: Forbidden
/smtp/bounces/day:
get:
summary: Get information about bounces for a 24-hour period
operationId: getSmtpBouncesDay
tags:
- Bounces
x-ai-role: email_deliverability_expert
x-ai-description: >
Retrieves a report of all hard and soft bounces encountered in the last
24 hours. Vital for maintaining a healthy sender reputation.
x-ai-reasoning-instructions:
- >-
Analyze the `smtp_answer_data` to categorize the reason for the
bounce.
- >-
Identify patterns that might indicate IP blacklisting or domain
issues.
x-ai-responding-instructions:
- Report the total number of bounces and list the most common reasons.
- Advise on removing high-frequency bouncers from active lists.
x-ai-suggestions:
- Check `total` vs `found` to see if pagination is needed.
x-ai-capabilities:
confirmation:
type: None
parameters:
- name: date
in: query
schema:
type: string
format: date
example: '2024-01-01'
- name: limit
in: query
schema:
type: integer
- name: offset
in: query
schema:
type: integer
responses:
'200':
description: Bounce report
content:
application/json:
schema:
type: object
properties:
total:
type: integer
emails:
type: array
items:
type: object
properties:
email_to:
type: string
sender:
type: string
send_date:
type: string
subject:
type: string
smtp_answer_code:
type: integer
smtp_answer_subcode:
type: string
smtp_answer_data:
type: string
request_limit:
type: integer
found:
type: integer
'401':
description: Unauthorized
'403':
description: Forbidden
/smtp/bounces/day/total:
get:
summary: Get total number of bounces
operationId: getSmtpBouncesTotal
tags:
- Bounces
x-ai-role: compliance_officer
x-ai-description: >
Quick count of bounces for the last 24-hour window. Provides a
high-level health metric for delivery.
x-ai-reasoning-instructions:
- >-
Compare this count with the total send volume to calculate bounce
rate.
x-ai-responding-instructions:
- State the total number of bounces detected.
x-ai-suggestions:
- If bounce rate exceeds 2%, trigger a deeper audit of the source list.
x-ai-capabilities:
confirmation:
type: None
responses:
'200':
description: Total bounce count
content:
application/json:
schema:
type: object
properties:
total:
type: integer
'401':
description: Unauthorized
'403':
description: Forbidden
/smtp/unsubscribe:
post:
summary: Unsubscribe a recipient
operationId: unsubscribeSmtpRecipients
tags:
- Unsubscribe
x-ai-role: compliance_officer
x-ai-description: >
Manually adds email addresses to the global suppression list for SMTP.
Essential for honoring external unsubscribe requests or managing legal
compliance.
x-ai-reasoning-instructions:
- Ensure all email addresses are validly formatted before submission.
x-ai-responding-instructions:
- Confirm that the addresses have been added to the suppression list.
x-ai-suggestions:
- Include descriptive comments for why the user was unsubscribed.
x-ai-capabilities:
confirmation:
type: Required
security_info:
data_handling:
- ResourceStateUpdate
requestBody:
required: true
content:
application/json:
schema:
type: array
items:
type: object
required:
- email
properties:
email:
type: string
comment:
type: string
responses:
'200':
description: Unsubscribe successful
content:
application/json:
schema:
type: object
properties:
result:
type: boolean
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
emails.empty:
summary: emails.empty
value:
message: Empty emails
error_code: 14
'401':
description: Unauthorized
'403':
description: Forbidden
delete:
summary: Remove an email from the unsubscribed list
operationId: removeSmtpUnsubscribe
tags:
- Unsubscribe
x-ai-role: compliance_officer
x-ai-description: >
Reinstates a suppressed email address, allowing future SMTP
communications. Should only be used when a user explicitly requests to
re-engage.
x-ai-reasoning-instructions:
- Verify that the user has given consent to be re-added.
x-ai-responding-instructions:
- Confirm removal from the suppression list.
x-ai-suggestions:
- Suggest sending a resubscription confirmation email for double opt-in.
x-ai-capabilities:
confirmation:
type: Required
security_info:
data_handling:
- ResourceStateUpdate
requestBody:
required: true
content:
application/json:
schema:
type: array
items:
type: string
responses:
'200':
description: Removal successful
content:
application/json:
schema:
type: object
properties:
result:
type: boolean
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
emails.empty:
summary: emails.empty
value:
message: Empty emails
error_code: 14
'401':
description: Unauthorized
'403':
description: Forbidden
get:
summary: Get a list of unsubscribed users
operationId: getSmtpUnsubscribed
tags:
- Unsubscribe
x-ai-role: marketing_automation_specialist
x-ai-description: >
Returns a list of all emails currently in the suppression list. Used to
synchronize external CRM systems with SendPulse state.
x-ai-reasoning-instructions:
- Filter by date if only recent unsubscribes are needed for sync.
x-ai-responding-instructions:
- Summarize the list of unsubscribed users found.
x-ai-suggestions:
- >-
Use `limit` and `offset` to process large suppression lists
incrementally.
x-ai-capabilities:
confirmation:
type: None
parameters:
- name: date
in: query
schema:
type: string
format: date
- name: limit
in: query
schema:
type: integer
- name: offset
in: query
schema:
type: integer
responses:
'200':
description: List of unsubscribed users
content:
application/json:
schema:
type: array
items:
type: object
properties:
email:
type: string
unsubscribe_by_link:
type: integer
unsubscribe_by_user:
type: integer
spam_complaint:
type: integer
date:
type: string
'401':
description: Unauthorized
'403':
description: Forbidden
'422':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
tariff.not_allowed:
summary: tariff.not_allowed
value:
message: Your tariff does not allow the operation
error_code: 422
/smtp/unsubscribe/search:
get:
summary: Get information about a contact's subscription status
operationId: searchSmtpUnsubscribe
tags:
- Unsubscribe
parameters:
- name: email
in: query
required: true
schema:
type: string
x-ai-role: compliance_officer
x-ai-description: >
Checks if a specific email address is currently suppressed. A
preventative check to avoid sending to users who have opted out.
x-ai-reasoning-instructions:
- Run this check before manually triggering a high-value email.
x-ai-responding-instructions:
- Clearly state if the user is currently unsubscribed or not.
x-ai-suggestions:
- If `result` is true, do not attempt to send emails to this address.
x-ai-capabilities:
confirmation:
type: None
responses:
'200':
description: Subscription status
content:
application/json:
schema:
type: object
properties:
result:
type: boolean
'401':
description: Unauthorized
'403':
description: Forbidden
'422':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
email.empty:
summary: email.empty
value:
message: Empty email parameter
error_code: 422
email.invalid:
summary: email.invalid
value:
message: Wrong email parameter
error_code: 422
/smtp/resubscribe:
post:
summary: Resubscribe a recipient
operationId: resubscribeSmtpRecipient
tags:
- Unsubscribe
x-ai-role: marketing_automation_specialist
x-ai-description: >
Sends a formal resubscription request email to a suppressed contact.
This is a 'double opt-in' safety mechanism to ensure valid
re-engagement.
x-ai-reasoning-instructions:
- Be aware of the 24-hour limit (max 5 emails per account).
- Select the appropriate language (`lang`) based on the user's profile.
x-ai-responding-instructions:
- Confirm the request email has been sent.
- Remind the user of the daily rate limit for this action.
x-ai-suggestions:
- Default to `en` if user language is unknown.
x-ai-capabilities:
confirmation:
type: Required
security_info:
data_handling:
- ResourceStateUpdate
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- email
- sender
properties:
email:
type: string
sender:
type: string
lang:
type: string
enum:
- ru
- en
- ua
- tr
- es
- pt
default: en
responses:
'200':
description: Resubscription email sent
content:
application/json:
schema:
type: object
properties:
result:
type: boolean
id:
type: string
'401':
description: Unauthorized
'403':
description: Forbidden
'422':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
email.required:
summary: email.required
value:
message: Argument email missing
error_code: 422
email.invalid:
summary: email.invalid
value:
message: Argument email is invalid
error_code: 422
sender.required:
summary: sender.required
value:
message: Argument sender missing
error_code: 422
lang.string:
summary:
# --- truncated at 32 KB (43 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sendpulse/refs/heads/main/openapi/sendpulse-smtp-openapi.yml