stampr postal mail api

The stampr api allows access to advanced features provided by https://stam.pr/ including variable data and integration with third-party systems.

Endpoint: https://stam.pr -- GET https://stam.pr/api/health

Throttling: 10 req/s

Overview

The API can be broken up into 3 objects:

Batch (container for mailings)
Config (configuration for mailings)
Mailing

Data Relationships:

Batches contain Mailings
Batches have exactly one Config
Configs can be used for multiple Batches
Mailings must belong to a Batch

Diagram

  ____________________________
 /           _______________   \
|           /               \   |
|  Batches |    Mailings    |   |
|           \______________/    |
 \_____________________________/
     |
   Configs

Example in Pseudo Code

Config = CreateConfig(configOptions)
Batch = CreateBatch(Config, batchOptions)
for (i = 1 to 100)
{
  Mailing = CreateMailing(Batch, mailingOptions)
}

Authentication

Basic
HMAC (Coming soon)

Configs

Mail configurations are largely placeholders for future content.

Create New Config

POST /api/configs

Returns: Config Object

Create a new mailing configuration to be used with Batches.

size (string)	Required Valid values (case sensitive): * "standard" * "postcard" * "legal" Currently, only standard is supported. This should be hidden in the API, and always send "standard"
turnaround (string)	Required Valid values (case sensitive): * "weekend" * "overnight" * "threeday" * "week" Currently ignored. All mailings are processed in the order they are received regardless of the value here. This should be hidden in the API, and always send "threeday"
style (string)	Required Valid values (case sensitive): * "color" * "mono" Currently, only color is supported. This should be hidden in the API, and always send "color"
output (string)	Required Valid values (case sensitive): * "single" * "double" Currently, only single is supported. This should be hidden in the API, and always send "single"
returnenvelope (bool)	Required Currently ignored. This should be hidden in the API, and always send `false`

Search/List Configs

GET /api/configs/:id
GET /api/configs/browse/all
GET /api/configs/browse/all/:paging

Returns: Config[] (Paged Array of Config Objects)

paging - 0-based page index (page size is set on the server and cannot be changed at this time)

Batches

Create New Batch

POST /api/batches

Returns: Batch Object

Create a new, empty batch container to be used with Mailings.

config_id (integer)	Required The configuration all the mailings in this batch will conform to.
template (string/HTML)	Optional This will be the base HTML template used for all mailings created in this batch. Templates use mustache syntax. -- Details: http://mustache.github.io/ Example Template: "Hello {{name}}!" And then `$name` can be sent via the Mailing and the template will be merged with the data and rendered.
status (string)	Optional Valid values (case sensitive): * "processing" (default, if excluded) * "hold" When mailings are created, they are printed and shipped as soon as possible. Set a batch to "hold" and mailing will not be printed until the batch status is changed to processing.

Modify Batch by Batch ID

POST /api/batches/:id

Returns: true on success

batch_id (integer)	Required The batch to be updated.
status (string)	Required Valid values (case sensitive): -"processing" -"hold" -"archive" If changing from processing to hold, all mailings currently in production will be sent.

Delete a Batch by ID

DELETE /api/batches/:id

Returns: true on success

Batches that contain mailings cannot be deleted. Only empty batches are allowed.

Search/List Batches

GET /api/batches/:id
GET /api/batches/with/:status
GET /api/batches/with/:status/:start
GET /api/batches/with/:status/:start/:end
GET /api/batches/with/:status/:start/:end/:paging
GET /api/batches/browse/:start
GET /api/batches/browse/:start/:end
GET /api/batches/browse/:start/:end/:paging

Returns: Batch[] (Paged Array of Batch Objects)

-status - Any valid Batch status -- 'processing', 'hold' -start - Any date time that can be parsed by moment.js -end - Any date time that can be parsed by moment.js -paging - 0-based page index (page size is set on the server and cannot be changed at this time)

Search/List Mailings belonging to Batch

GET /api/batches/:id/mailings
GET /api/batches/:id/mailings/with/:status
GET /api/batches/:id/mailings/with/:status/:start
GET /api/batches/:id/mailings/with/:status/:start/:end
GET /api/batches/:id/mailings/with/:status/:start/:end/:paging
GET /api/batches/:id/mailings/browse/:start
GET /api/batches/:id/mailings/browse/:start/:end
GET /api/batches/:id/mailings/browse/:start/:end/:paging

Returns: Mailing[] (Paged Array of Mailing Objects)

status - Any valid Mailing status -- 'received','render','error','queued','assigned','processing','printed','shipped'
start - Any date time that can be parsed by moment.js. It should be URL encoded.
end - Any date time that can be parsed by moment.js. It should be URL encoded.
paging - 0-based page index (page size is set on the server and cannot be changed at this time)

Mailings

Create New Mailing

POST /api/mailings

Returns: Mailing Object

batch_id (integer)	Required The Batch the Mailing belongs to.
address (string)	Required The postal mailing address to send the mailing to. (Not Implement Yet. This Can be Ignored) String provided should contain an address that conforms to the USPS CASS system -- http://en.wikipedia.org/wiki/Coding_Accuracy_Support_System
returnaddress (string)	Required The postal return mailing address. (Not Implement Yet. This Can be Ignored) String provided should contain an address that conforms to the USPS CASS system -- http://en.wikipedia.org/wiki/Coding_Accuracy_Support_System
format (string)	Required Valid values (case sensitive): -"json" - Key/Value data to be merged and rendered into Batch template -"html" - HTML to be rendered and sent as-is -"pdf" - PDF to be mailed -"none" - No data being provided. Send Batch template as-is. This is the format of the data being provided. -JSON is useful for variable-data mailings (mail merge), when combined with Batch template. -HTML is useful for the same reason, but provides more control to the end-user. -PDF is identical to HTML, only data is rendered as PDF. -None allows many duplicate mailings (Batch template) to be sent.
data (string)	Required, unless format is "none" The data payload in the format specified. Data should be always be base64 encoded. Example: HtmlData = 'hello' HtmlMailing.Data = Base64(HtmlData) PdfData = io.File('my.pdf') PdfMailing.Data = Base64(PdfData) </code> </td> </tr> <tr> <th>md5 (string) -- lowercase hex, case-sensitive</th> <td> Optional<br> <br> To ensure data integrity, an optional MD5 hash of the data can be supplied. See `data` above for details on how to encode data prior to md5 hashing.<br> It is calculated as follows:<br> <code> RawData = Raw_User_Data;<br> Data = Base64( RawData );<br> Md5Hash = Md5( Data );<br> </code> </td> </tr>

Delete a Mailing by Mailing ID

DELETE /api/mailings/:id

Returns: true on success

In order to delete a mailing, the mailing's status must be received. Mailing statuses will only be received if the owning batch has a status of hold.

Search/List Mailings

GET /api/mailings/:id
GET /api/mailings/with/:status
GET /api/mailings/with/:status/:start
GET /api/mailings/with/:status/:start/:end
GET /api/mailings/with/:status/:start/:end/:paging
GET /api/mailings/browse/:start
GET /api/mailings/browse/:start/:end
GET /api/mailings/browse/:start/:end/:paging

Returns: Mailing[] (Paged Array of Mailing Objects)

status - Any valid Mailing status -- 'received','render','error','queued','assigned','processing','printed','shipped'
start - Any date time that can be parsed by moment.js
end - Any date time that can be parsed by moment.js
paging - 0-based page index (page size is set on the server and cannot be changed at this time)

Tests

Simple Round Trip Test

GET /api/test/ping

Returns: Object with single key "pong" and a value of the current Date/Time of the server

Check API health

GET /api/health

Returns: string

Returns the exact string "ok" (with quotes) when everything is ok. =]

This is the only resource that doesn't require authentication.

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
.gitignore		.gitignore
README.md		README.md

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

stampr postal mail api

Overview

Data Relationships:

Diagram

Example in Pseudo Code

Authentication

Configs

Create New Config

Search/List Configs

Batches

Create New Batch

Modify Batch by Batch ID

Delete a Batch by ID

Search/List Batches

Search/List Mailings belonging to Batch

Mailings

Create New Mailing

Delete a Mailing by Mailing ID

Search/List Mailings

Tests

Simple Round Trip Test

Check API health

About

Releases

Packages

stampr/stampr-api

Folders and files

Latest commit

History

Repository files navigation

stampr postal mail api

Overview

Data Relationships:

Diagram

Example in Pseudo Code

Authentication

Configs

Create New Config

Search/List Configs

Batches

Create New Batch

Modify Batch by Batch ID

Delete a Batch by ID

Search/List Batches

Search/List Mailings belonging to Batch

Mailings

Create New Mailing

Delete a Mailing by Mailing ID

Search/List Mailings

Tests

Simple Round Trip Test

Check API health

About

Resources

Stars

Watchers

Forks

Releases

Packages 0

Packages