> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paubox.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Send a message
## OpenAPI
````yaml openapi1 POST /messages
openapi: 3.0.0
info:
title: Paubox Email API
description: >
Public documentation for Paubox's Transactional Email API
## Authentication
**IMPORTANT**: This API uses a custom authentication format that requires
the "Token token=" prefix.
All requests must include the Authorization header in this exact format:
```
Authorization: Token token=YOUR_API_KEY
```
**Note for Code Generation Tools**: Auto-generated code from this
specification may need to be modified to include the "Token token=" prefix,
as most generators expect standard Bearer token format.
version: 1.0.0
servers:
- url: https://api.paubox.net/v1/{api_username}
description: Paubox Email API
variables:
api_username:
description: Your Paubox Email API endpoint username
default: YOUR_API_USERNAME
security:
- PauboxToken: []
tags:
- name: Messages
description: Send individual or bulk transactional email
- name: Dynamic Templates
description: Manage and use dynamic Handlebars templates for email content
paths:
/messages:
post:
tags:
- Messages
summary: Send a single email message
operationId: sendMessage
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SingleSendRequest'
examples:
basic:
summary: Minimal text+HTML example
description: |
**CURL Example:**
```bash
curl --request POST \
--url https://api.paubox.net/v1/YOUR_API_USERNAME/messages \
--header 'Authorization: Token token=YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{"data":{"message":{"recipients":["recipient@host.com"],"headers":{"subject":"Hello from the Paubox Email API","from":"sender@verifieddomain.com"},"content":{"text/plain":"Hello world","text/html":"Hello world
"}}}}'
```
value:
data:
message:
recipients:
- recipient@host.com
headers:
subject: Hello from the Paubox Email API
from: sender@verifieddomain.com
content:
text/plain: Hello world
text/html: Hello world
full:
summary: >-
Full example with bcc, reply-to, custom header, attachment,
and overrides
value:
data:
message:
recipients:
- recipient@host.com
- Recipient Name
bcc:
- recipient3@host.com
- Recipient Name
cc:
- cc.name
headers:
subject: sample email
from: sender@authorized_domain.com
reply-to: Sender Name
x-custom-header: sample custom header
List-Unsubscribe: >-
content:
text/plain: Hello World!
text/html: Hello World!
attachments:
- fileName: hello_world.txt
contentType: text/plain
content: SGVsbG8gV29ybGQh
override_open_tracking: true
override_link_tracking: true
unsubscribe_url: https://your_url_here.com
required: true
responses:
'200':
description: Message accepted
content:
application/json:
schema:
$ref: '#/components/schemas/SingleSendResponse'
examples:
ok:
value:
sourceTrackingId: 3d38ab13-0af8-4028-bd45-52e882e0d584
customHeaders:
X-Custom-Header: value
data: Service OK
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- PauboxToken: []
components:
schemas:
SingleSendRequest:
required:
- data
type: object
properties:
data:
$ref: '#/components/schemas/SingleSendRequest_data'
SingleSendResponse:
type: object
properties:
sourceTrackingId:
type: string
description: Identifier for tracking the message source.
customHeaders:
type: object
additionalProperties:
type: string
data:
type: string
example: Service OK
ErrorResponse:
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/ErrorResponse_errors'
SingleSendRequest_data:
required:
- message
type: object
properties:
message:
$ref: '#/components/schemas/Message'
override_open_tracking:
type: boolean
description: Set to true to enable open tracking for this message.
override_link_tracking:
type: boolean
description: >-
Set to true to enable click tracking for this message (up to 1000
links).
unsubscribe_url:
type: string
description: URL to redirect unsubscribe requests for unsubscribe tracking.
format: uri
ErrorResponse_errors:
type: object
properties:
code:
type: integer
title:
type: string
details:
type: string
Message:
required:
- content
- headers
- recipients
type: object
properties:
recipients:
minItems: 1
type: array
items:
type: string
description: >-
Email address, optionally with display name (e.g., "J. Smith
").
bcc:
type: array
items:
type: string
cc:
type: array
items:
type: string
headers:
$ref: '#/components/schemas/MessageHeaders'
allowNonTLS:
type: boolean
description: >
Allow delivery over non-TLS rather than converting to a Secure
Portal message. Not HIPAA-compliant if the message contains PHI.
default: false
forceSecureNotification:
type: boolean
description: >
Force delivery as a Paubox Secure Message; recipient gets a pickup
notification with a link.
default: false
content:
$ref: '#/components/schemas/MessageContent'
attachments:
type: array
items:
$ref: '#/components/schemas/Attachment'
MessageHeaders:
required:
- from
- subject
type: object
properties:
subject:
type: string
from:
type: string
description: Must match the verified domain of your API key.
reply-to:
type: string
description: >-
Reply-to address; must match a verified domain if different from
from.
List-Unsubscribe:
type: string
description: >
Insert a List-Unsubscribe header (mailto and/or http). See RFC
guidance for syntax.
List-Unsubscribe-Post:
type: string
description: Used in conjunction with List-Unsubscribe header.
x-custom-header:
type: string
description: >-
Example custom header; any custom header may be added with an X-
prefix.
additionalProperties:
type: string
description: Any additional X- prefixed custom header values.
MessageContent:
type: object
properties:
text/plain:
type: string
description: Plain text message body. Required if text/html is not provided.
text/html:
type: string
description: >
HTML message body. May be HTML-escaped, base64-encoded, or a valid
unescaped string. CSS in