Overview

Current Endpoint: https://api.simplecertifiedmail.com/RESTv4.0

SimpleCertifiedMail.com's REST API exposes a number of methods that support third party integration with our service. Integrators may create Certified or Priority Cover Sheets, and follow up by looking for status updates via our suite of tracking methods. The REST API also supports our partners who need outsourced printing services by exposing the "queuePrintItem" method that accepts a PDF representation of the piece to be printed and mailed.

To get started with your integration, please sign up for a developer account by clicking the "Login" icon and filling out the "Register Here" section. You will then have access to your account page and a test Partner Key that is used in the token calls. You will also be able to make use of the "Online API Tester" to get a feel for the format of the calls prior to coding your solution.

For clients who wish to create and mail their own Cover Sheets, please examine documentation on the "Get Certified Mail" and "Get Priority Label" methods. For tracking, there are a few options but the basics are covered with "Get Document Status".

Customers looking to make use of the "Mailing Services" features will want to look at the "Queue Print Item" documentation, followed by the "Get Document Status By Doc ID" for tracking.

Finally, when you are ready to go live and begin creating production pieces you will need to request a live Partner Key. This is accomplished from the "My Account" screen, at the bottom of the page where it says "Request Live Partner Key". To obtain a live partner key you must have access to the User Name, Password, and Client Code for a live SimpleCertifiedMail.com client. This is an account created through the "Sign Up" process found at https://www.simplecertifiedmail.com. A live client will have one or more valid payment instruments on file with SimpleCertifiedMail.com and be prefunded for creating live postage.

For questions or concerns please email apisupport@simplecertifiedmail.com

Get Access Token

Purpose

The SCM REST API utilizes bearer token authentication. Calls to each method require users to present a valid token in the header. To generate the token you will need to set User Name, Password, Client Code, and Partner Key and hit the /token service. Note: The token endpoint is the only method that requires a form-urlencoded POST as demonstrated below.

Route

https://api.simplecertifiedmail.com/RESTv4.0/token

Sample POST

POST https://api.simplecertifiedmail.com/RESTv4.0/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
User-Agent: PostmanRuntime/7.26.2
Accept: */*
Host: api.simplecertifiedmail.com
Accept-Encoding: gzip, deflate, br
Connection: keep-alive
Content-Length: 124

grant_type=password&username=********&password=********&PartnerKey=4a267c9e-ad6d-4025-b3c1-28c380664a34&ClientCode=green

Sample Outputs

Usage on API calls

The bearer token generated in the token request above should be appended to the Authorization header of each subsequent API call.
Header must be in the format of "Authorization: Bearer " followed by the generated token.
The following is a brief sample of usage:

POST https://api.simplecertifiedmail.com/RESTv4.0/api/scm/getcertifiedlabel HTTP/1.1
Authorization: Bearer {your token here}
Content-Type: application/json
User-Agent: PostmanRuntime/7.28.4
Accept: */*
Host: api.simplecertifiedmail.com
Accept-Encoding: gzip, deflate, br
Connection: keep-alive
Content-Length: 771

Get Certified Label

Purpose

Fetch a USPS Certified Mail label. Users must pass along the sender and recipient data as well as the information related to label size and weight. The return will contain the tracking code and a base64 encoded representation of the label.

Route

https://api.simplecertifiedmail.com/RESTv4.0/api/scm/getcertifiedlabel

Sample Inputs

Sample Outputs

Get Priority Label

Purpose

Fetch a USPS Priority Mail label. Users must pass along the sender and recipient data as well as the information related to label size and weight. The return will contain the tracking code and a base64 encoded representation of the label.

Route

https://api.simplecertifiedmail.com/RESTv4.0/api/scm/getprioritylabel

Sample Inputs

Sample Outputs

Queue Print Item

Purpose

This method is at the heart of SCM’s outsourced printing offering. Users of this method can enqueue mail pieces for third party printing and mailing via a variety of services. If Certified Mail is chosen as an additional service, SCM will perform the same tracking/reporting/retention on these items as those labels produced via the web application or our two “Get Label” API methods. With “Queue Print Item” the user must transmit a base64 encoded PDF representation of the letter for printing along with the sender and recipient information.

Requirements

  • Pages must be standard 8 1/2" x 11" pages Portrait format.
  • The margins for all four corners for all pages must be a minimum of .5".
  • There should be no imbedded items in the "Clear Space" in the margins.

Route

https://api.simplecertifiedmail.com/RESTv4.0/api/scm/queueprintitem

Sample Inputs

Sample Outputs

Get Document Status

Purpose

Get the currently-available tracking status for the specified piece(s). User may pass in either a single tracking code in the PIC field, or specify a date range (no greater than 1 month) to retrieve tracking data on a set of items with a send date within the date range. If both a PIC and a date range are passed in, the single PIC is used and the date range is ignored.

Route

https://api.simplecertifiedmail.com/RESTv4.0/api/scm/getdocumentstatus

Sample Inputs

Sample Outputs

Get Document Status By Ref

Purpose

This method is similar to “Get Document Status”, but performs a search by the “ToReference” parameter instead of tracking number or date range.

Route

https://api.simplecertifiedmail.com/RESTv4.0/api/scm/getdocumentstatusbyref

Sample Inputs

Sample Outputs

Get Document Status By Item Id

Purpose

Another means of searching for document status, in this case by the “Item ID” parameter.

Route

https://api.simplecertifiedmail.com/RESTv4.0/api/scm/getdocumentstatusbyitemid

Sample Inputs

Sample Outputs

Get Document Status By Update Date

Purpose

Get the currently-available tracking status for the specified piece(s) with Update Dates within the specified range. User may pass in a date range of no greater than 1 month. Time fields may also be used to narrow selection to more specific ranges.

Route

https://api.simplecertifiedmail.com/RESTv4.0/api/scm/getdocumentstatusbyupdatedate

Sample Inputs

Sample Outputs

Get Production Report

Purpose

Provides a report on production across a timeframe, or a daily snapshot. The results are transmitted as a base64 encoded Excel document with a row per item printed.

Route

https://api.simplecertifiedmail.com/RESTv4.0/api/scm/getproductionreport

Sample Inputs

Sample Outputs

Get Print Status Update

Purpose

Meant as a supplementary method for “Queue Print Item”, this method returns a set of all unviewed status messages related to pieces sent via “Queue Print Item”. Requesting these messages then flags the status entries as “viewed” so they will not be retransmitted.

Route

https://api.simplecertifiedmail.com/RESTv4.0/api/scm/getprintstatusupdate

Sample Inputs

Sample Outputs

Get Document Status By Document ID

Purpose

Another means of searching for document status, in this case by the "ID" parameter. This method is helpful for fetching status on a single piece created via the "QueuePrintItem" endpoint, and takes as the input "ID" the "QueueID" returned from that method.

Route

https://api.simplecertifiedmail.com/RESTv4.0/api/scm/getdocumentstatusbydocid

Sample Inputs

Sample Outputs

Get Letter By Document ID

Purpose

This method will return the original Letter pdf file sent when a single piece is created via the "QueuePrintItem" endpoint, and takes as the input "ID" the "QueueID" returned from that method.

Route

https://api.simplecertifiedmail.com/RESTv4.0/api/scm/getletterbydocid

Sample Inputs

Sample Outputs