Physical Post

Endpoints for sending physical letters and postcards in the post

Send letters

Queues one or more letters for sending on behalf of the practice

Securityapi_key or azure_auth
Request
path Parameters
SiteSlug
required
string <slug> (Slug) ^[osl][a-zA-Z0-9]{3,}$

The Slipstream slug that uniquely identifies a physical practice

Example: s8n6EzC
Request Body schema: application/json
required

The details of the letter to send

Array
Express
boolean or null

Whether the letter should be sent by express delivery. If omitted, the default is standard delivery.

DoubleSided
boolean or null

Whether the letter should be single or double sided. If omitted, the default is single sided.

Color
boolean or null

Whether the letter should be printed in color. If omitted, the default is black and white.

PmsSpecificId
required
string

The unique ID of the letter in the pms system

ScheduledSendDate
string <date-time>

The date to send the letter - omit or blank to send immediately

required
object or null (Addressee)

The name and identity of a person

required
object (StreetAddress)

Information about a street address.

required
object (DataUri)

A URI that can be used to request data (usually files) from the PMS with a GET request. Typical implementations would be:

SkipAddressValidation
boolean or null

Whether to skip address validation of the recipient address

property name*
additional property
any
Responses
202

The response of the physical letter sending request

400

Malformed Request (ProblemDetails)

401

Unauthorized - Provide proof of identity (ProblemDetails)

403

Forbidden - Insufficient permissions (ProblemDetails)

404

Not Found - Could not find a matching entity (ProblemDetails)

422

Unprocessable - Request was well formed but could not be actioned (ProblemDetails)

429

Too many requests - Chill out (ProblemDetails)

4XX

User Error (ProblemDetails)

5XX

Server Error (ProblemDetails)

post/sites/{SiteSlug}/physicalpost/letter
Request samples
application/json
[]
Response samples
application/json
{
  • "Succeeded": [
    ],
  • "Failed": [
    ]
}

Get a paginated list of all letter details owned by a site

Gets a list of letters

Securityapi_key or azure_auth
Request
path Parameters
SiteSlug
required
string <slug> (Slug) ^[osl][a-zA-Z0-9]{3,}$

The Slipstream slug that uniquely identifies a physical practice

Example: s8n6EzC
query Parameters
pageSize
integer <int32> [ 1 .. 250 ]

The page number to retrieve

Example: pageSize=50
nextPageToken
string

A token retrieved from a previous request, used to retrieve the next page of results

status
string (LetterStatus)

The status of the letters to retrieve - if not provided, all statuses will be returned

Enum Value Description
Unknown

The status of the letter is unknown - Default value - use when filtering letters when status value is not important

Created

The letter has been created but has not yet been sent to the mail provider

Pending

Sent to the mail provider and awaiting status updates from the mail provider

TransientFailure

A transient failure occured when attempting to send to mail provider, will retry

InvalidAddress

The destination address supplied is invalid

Failed

An unrecoverable failure occured when attempting to send to mail provider

Printing

The letter is currently being printed by the mail provider

InTransit

The letter is currently in transit to the destination address

Completed

Sucessfully delvered to the destination address

Cancelled

The letter was cancelled before it was sent

dateFrom
string <date>

The date to retrieve letters from - if not provided, all letters will be returned

includeHistory
boolean

If true, the response will include the history of the letter

Example: includeHistory=false
Responses
200

The letter details for this site

400

Malformed Request (ProblemDetails)

401

Unauthorized - Provide proof of identity (ProblemDetails)

403

Forbidden - Insufficient permissions (ProblemDetails)

404

Not Found - Could not find a matching entity (ProblemDetails)

422

Unprocessable - Request was well formed but could not be actioned (ProblemDetails)

429

Too many requests - Chill out (ProblemDetails)

4XX

User Error (ProblemDetails)

5XX

Server Error (ProblemDetails)

get/sites/{SiteSlug}/physicalpost/letter
Request samples
Response samples
application/json
{
  • "Items": [
    ],
  • "NextPageToken": "eyJ0eXAiOi"
}

Get the letter details of a specific letter

Get the details of a letter

Securityapi_key or azure_auth
Request
path Parameters
SiteSlug
required
string <slug> (Slug) ^[osl][a-zA-Z0-9]{3,}$

The Slipstream slug that uniquely identifies a physical practice

Example: s8n6EzC
LetterId
required
string <uuid>

The unique identifier (GUID) of the letter in slipstream

Example: 44088399-d916-4de5-9f0a-dca7b3d07df2
query Parameters
includeHistory
boolean

If true, the response will include the history of the letter

Example: includeHistory=false
Responses
200

The letter details

400

Malformed Request (ProblemDetails)

401

Unauthorized - Provide proof of identity (ProblemDetails)

403

Forbidden - Insufficient permissions (ProblemDetails)

404

Not Found - Could not find a matching entity (ProblemDetails)

422

Unprocessable - Request was well formed but could not be actioned (ProblemDetails)

429

Too many requests - Chill out (ProblemDetails)

4XX

User Error (ProblemDetails)

5XX

Server Error (ProblemDetails)

get/sites/{SiteSlug}/physicalpost/letter/{LetterId}
Request samples
Response samples
application/json
{
  • "Express": false,
  • "DoubleSided": false,
  • "Color": false,
  • "LetterId": "string",
  • "RecordId": "string",
  • "PmsSpecificId": "string",
  • "Addressee": {
    },
  • "Address": {
    },
  • "Pdf": {},
  • "Created": "2024-10-24T14:30:15+02:00",
  • "ScheduledSendDate": "2024-10-24T14:30:15+02:00",
  • "Sent": "2024-10-24T14:30:15+02:00",
  • "State": "Sent",
  • "StateDetails": "The letter was sent to the postal provider",
  • "Description": "A4 Letter [BlackAndWhite, Standard Delivery, Sent]",
  • "History": [
    ]
}