openapi: 3.2.0
info:
title: Paubox Email Messages 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.com/v1/email
description: Paubox Email API
security:
- PauboxToken: []
tags:
- name: Messages
description: Send individual or bulk transactional email
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:**\n```bash\ncurl --request POST \\\n --url https://api.paubox.com/v1/email/messages \\\n --header 'Authorization: Token token=YOUR_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --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
\"}}}}'\n```\n"
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: []
/bulk_messages:
post:
tags:
- Messages
summary: Send multiple email messages (batch)
description: 'Sends multiple messages in one request. Paubox recommends batches of 50 or fewer. Source tracking IDs are returned in the same order as the messages array.
'
operationId: sendBulkMessages
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BulkSendRequest'
examples:
twoMessages:
summary: Two-message batch
value:
data:
messages:
- recipients:
- recipient@host.com
- Recipient Name
bcc:
- recipient3@host.com
- Recipient Name
headers:
subject: sample email
from: sender@authorized_domain.com
reply-to: Sender Name
x-custom-header: sample custom header
content:
text/plain: Hello World!
text/html: Hello World!
attachments:
- fileName: hello_world.txt
contentType: text/plain
content: SGVsbG8gV29ybGQh
allowNonTLS: false
forceSecureNotification: false
- recipients:
- recipient2@host.com
- Recipient Name
headers:
subject: sample email
from: sender@authorized_domain.com
reply-to: Sender Name
content:
text/plain: Hello World!
text/html: Hello World!
attachments:
- fileName: hello_world.txt
contentType: text/plain
content: SGVsbG8gV29ybGQh
required: true
responses:
'200':
description: Batch accepted
content:
application/json:
schema:
$ref: '#/components/schemas/BulkSendResponse'
examples:
ok:
value:
messages:
- sourceTrackingId: 3d38ab13-0af8-4028-bd45-999999999999
customHeaders:
X-Custom-Header: value
data: Service OK
- sourceTrackingId: 3d38ab13-0af8-4028-bd45-000000000000
customHeaders:
X-Custom-Header: value
data: Service OK
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- PauboxToken: []
/message_receipt:
get:
tags:
- Messages
summary: Get email disposition
description: Retrieve delivery status, open tracking, and click tracking information for a sent message
operationId: getMessageReceipt
parameters:
- name: sourceTrackingId
in: query
description: The tracking ID returned when the message was sent
required: true
schema:
type: string
format: uuid
example: 6e1cf9a4-7bde-4834-8200-ed424b50c8a7
responses:
'200':
description: Message disposition data
content:
application/json:
schema:
$ref: '#/components/schemas/MessageReceiptResponse'
examples:
delivered:
summary: Delivered message with open and click tracking
value:
sourceTrackingId: 6e1cf9a4-7bde-4834-8200-ed424b50c8a7
data:
message:
id:
message_deliveries:
- recipient: recipient@host.com
status:
deliveryStatus: delivered
deliveryTime: Mon, 23 Apr 2018 13:27:34 -0700
openedStatus: opened
openedTime: Mon, 23 Apr 2018 13:27:51 -0700
total_opens: 1
distinct_opens: 1
total_click_count: 2
clicks_per_link:
- click_count: 1
target_url: amazon.com
- click_count: 1
target_url: ebay.com
unsubscribed: false
'404':
description: Message not found
content:
application/json:
schema:
$ref: '#/components/schemas/MessageReceiptErrorResponse'
examples:
notFound:
summary: Message not found
value:
errors:
- code: 404
title: Message was not found
details: Message with this tracking id was not found
sourceTrackingId: 6e1cf9a4-7bde-4834-8d200-ed424b50c8a7
security:
- PauboxToken: []
components:
schemas:
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