Back to top

CivicSource Mailhouse API

The client-facing API of the CivicSource mailhouse.

📝 All Mailhouse endpoints will accept gzip-encoded request payloads, so long as the appropriate Content-Encoding: gzip header is sent. This is mostly useful when creating a new batch.

🛂 All requests must be authorized by first requesting an auth token from our SSO API.

Batches

Batches are groupings of letters that need to be mailed. When you create a batch, it will be queued for mailing along with other mail batches from your application and others. Once in the queue, the mailhouse operator will decide (based on print capacity, target mailing dates, etc.) which batches should be merged into a mail job, and begin the printing process. Batches always include letters with a common target mail date, paper selection, return address, and mail class (First Class or Certified).

Batch

Create a new batch
POST/v2/batches

Creates a new batch from a list of letters and batch settings. An identifier for the batch will be generated and returned in the response.

Example URI

POST https://csdev-mailhouse-hotfix.azurewebsites.net/v2/batches
Request  Create a new batch
HideShow
Headers
Content-Type: application/json
Accept: application/json
Authorization: Bearer <token>
Content-Encoding: gzip ***if request payload is compressed***
Body
{
  "mailClass": "FirstClass",
  "electronicReturnReceipt": false,
  "usePerforatedPaper": true,
  "targetMailDate": "2019-05-10",
  "letters": [
    {
      "letterRefId": "L0000004",
      "name1": "John Doe",
      "name2": "C/O Jane Smith",
      "address1": "123 Main Street",
      "address2": "Suite 200",
      "city": "New Orleans",
      "state": "LA",
      "postalCode": "70112",
      "country": "US",
      "originalDocumentPath": "s3://bucket-name/object/key.pdf",
      "impressionCount": 3
    }
  ],
  "letterCount": 765,
  "returnAddress": "PO Box 52138\\nNew Orleans LA 70153"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "mailClass": {
      "type": "string",
      "enum": [
        "FirstClass",
        "Certified"
      ],
      "description": "Type of mail service. First Class Mail, or Certified Mail which includes a return receipt."
    },
    "electronicReturnReceipt": {
      "type": "boolean",
      "description": "Must be `true` for Certified Mail (we currently do not offer Form 3811 return receipts to external mailers). Ignored for First Class Mail."
    },
    "usePerforatedPaper": {
      "type": "boolean",
      "description": "If true, the first sheet of the letter (after the cover sheet) will be printed on perforated paper. Typically used for payment notices."
    },
    "targetMailDate": {
      "type": "string",
      "description": "Target date to have batch mailed by. Must be in ISO 8601 format. Time component will be ignored."
    },
    "letters": {
      "type": "array",
      "description": "Metadata of *all* letters, if providing letters immediately."
    },
    "letterCount": {
      "type": "number",
      "description": "Expected letter count. Batch will be considered ready for print acceptance once the number of letters in the batch equals this number."
    },
    "returnAddress": {
      "type": "string",
      "description": "The address to which undeliverable letters will be returned by the post office. This will be printed on each letter."
    }
  },
  "required": [
    "mailClass",
    "electronicReturnReceipt",
    "usePerforatedPaper",
    "targetMailDate",
    "letterCount",
    "returnAddress"
  ]
}
Response  200
HideShow

The batch was successfully created.

The identifier of the created batch can be found in the id key of the response object.

Headers
Content-Type: application/json
Location: /v2/batches/ABCD1234
Body
{
  "id": "ABCD1234",
  "mailClass": "FirstClass",
  "electronicReturnReceipt": false,
  "usePerforatedPaper": false,
  "targetMailDate": "2019-05-10",
  "letterCount": 0,
  "expectedLetterCount": 765
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Identifier for the created batch."
    },
    "mailClass": {
      "type": "string",
      "enum": [
        "FirstClass",
        "Certified"
      ]
    },
    "electronicReturnReceipt": {
      "type": "boolean"
    },
    "usePerforatedPaper": {
      "type": "boolean"
    },
    "targetMailDate": {
      "type": "string"
    },
    "letterCount": {
      "type": "number",
      "description": "Number of letters which have been received for this batch so format"
    },
    "expectedLetterCount": {
      "type": "number",
      "description": "Number of letters this batch will wait for before being considered ready for print acceptance"
    }
  }
}
Response  202
HideShow

The batch metadata has been received, and it will be created shortly (generally, within 5 minutes). Check the URL returned in the Location header for its current status. This response is only returned if the letters key is populated in the request object.

The identifier of the created batch can be found in the id key of the response object.

Headers
Content-Type: application/json
Location: /v2/batches/ABCD1234
Body
{
  "id": "ABCD1234",
  "mailClass": "FirstClass",
  "electronicReturnReceipt": false,
  "usePerforatedPaper": false,
  "targetMailDate": "2019-05-10",
  "letterCount": 0,
  "expectedLetterCount": 765
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Identifier for the created batch."
    },
    "mailClass": {
      "type": "string",
      "enum": [
        "FirstClass",
        "Certified"
      ]
    },
    "electronicReturnReceipt": {
      "type": "boolean"
    },
    "usePerforatedPaper": {
      "type": "boolean"
    },
    "targetMailDate": {
      "type": "string"
    },
    "letterCount": {
      "type": "number",
      "description": "Number of letters which have been received for this batch so format"
    },
    "expectedLetterCount": {
      "type": "number",
      "description": "Number of letters this batch will wait for before being considered ready for print acceptance"
    }
  }
}
Response  422
HideShow

The batch metadata was well-formed, but could not be processed. This usually means that some of the letter metadata failed validation, for example having a U.S. address without a ZIP code, or a duplicate letter ID.

Headers
Content-Type: application/json
Body
{
  "message": "Something bad happened"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "The error message"
    }
  }
}
Response  400
HideShow

Either the batch metadata contained a syntax error, the request payload was blank, or an enumeration value like mailClass contained an invalid string.

Headers
Content-Type: application/json
Body
{
  "message": "Something bad happened"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "The error message"
    }
  }
}
Response  403
HideShow

The request payload attempted to populate the id key.

Headers
Content-Type: application/json
Body
{
  "message": "Something bad happened"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "The error message"
    }
  }
}

Retrieve batch summary
GET/v2/batches/{batchId}

Retrieves information about the specified batch

Example URI

GET https://csdev-mailhouse-hotfix.azurewebsites.net/v2/batches/ABCD1234
URI Parameters
HideShow
batchId
string (required) Example: ABCD1234
Request  Retrieve batch summary
HideShow
Headers
Accept: application/json
Authorization: Bearer <token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "ABCD1234",
  "mailClass": "FirstClass",
  "electronicReturnReceipt": false,
  "usePerforatedPaper": false,
  "targetMailDate": "2019-05-10",
  "letterCount": 0,
  "expectedLetterCount": 765
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Identifier for the created batch."
    },
    "mailClass": {
      "type": "string",
      "enum": [
        "FirstClass",
        "Certified"
      ]
    },
    "electronicReturnReceipt": {
      "type": "boolean"
    },
    "usePerforatedPaper": {
      "type": "boolean"
    },
    "targetMailDate": {
      "type": "string"
    },
    "letterCount": {
      "type": "number",
      "description": "Number of letters which have been received for this batch so format"
    },
    "expectedLetterCount": {
      "type": "number",
      "description": "Number of letters this batch will wait for before being considered ready for print acceptance"
    }
  }
}
Response  404

Retrieve tracking summary
GET/v2/batches/{batchId}/tracking

Retrieves summated tracking information for the specified batch

Example URI

GET https://csdev-mailhouse-hotfix.azurewebsites.net/v2/batches/ABCD1234/tracking
URI Parameters
HideShow
batchId
string (required) Example: ABCD1234
Request  Retrieve tracking summary
HideShow
Headers
Accept: application/json
Authorization: Bearer <token>
Response  200
HideShow

Summated totals of letters in each state.

Headers
Content-Type: application/json
Body
{
  "status": "Initializing",
  "letterSummary": {
    "dropped": 0,
    "accepted": 0,
    "notMailable": 0,
    "inTransit": 568,
    "cannotReturnToSender": 0,
    "awaitingReturn": 35,
    "returned": 39,
    "delivered": 324,
    "other": 0
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "Initializing",
        "FailedToInitialize",
        "NotReady",
        "Printing",
        "Mailed"
      ]
    },
    "letterSummary": {
      "type": "object",
      "properties": {
        "dropped": {
          "type": "number",
          "description": "Letters dropped at origin post office."
        },
        "accepted": {
          "type": "number",
          "description": "Letters accepted by origin post office."
        },
        "notMailable": {
          "type": "number",
          "description": "Letters rejected by origin post office. Shouldn't happen under normal circumstances. *This status is terminal*."
        },
        "inTransit": {
          "type": "number",
          "description": "Letters in transit to its addressee."
        },
        "cannotReturnToSender": {
          "type": "number",
          "description": "Letters not delivered, but which cannot be returned. *This status is terminal*."
        },
        "awaitingReturn": {
          "type": "number",
          "description": "Letters in transit to the return address."
        },
        "returned": {
          "type": "number",
          "description": "Letters returned. *This status is terminal*."
        },
        "delivered": {
          "type": "number",
          "description": "Letters successfully delivered. *This status is terminal*."
        },
        "other": {
          "type": "number",
          "description": "Letters in an unknown state after USPS reported an unrecognized scan event."
        }
      },
      "description": "The count of letters in each state"
    }
  }
}
Response  404

Letters

Letter

Add letters to batch
POST/v2/batches/{batchId}/letters

Adds one or more letters to the specified batch.

Example URI

POST https://csdev-mailhouse-hotfix.azurewebsites.net/v2/batches/ABCD1234/letters
URI Parameters
HideShow
batchId
string (required) Example: ABCD1234
Request  Add letters to batch
HideShow
Headers
Content-Type: application/json
Accept: application/json
Authorization: Bearer <token>
Content-Encoding: gzip ***if request payload is compressed***
Body
[
  {
    "letterRefId": "L0000004",
    "name1": "John Doe",
    "name2": "C/O Jane Smith",
    "address1": "123 Main Street",
    "address2": "Suite 200",
    "city": "New Orleans",
    "state": "LA",
    "postalCode": "70112",
    "country": "US",
    "originalDocumentPath": "s3://bucket-name/object/key.pdf",
    "impressionCount": 3
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "letterRefId": {
        "type": "string",
        "description": "Reference identifier of the letter (unique within a batch). Must be exactly 8 characters."
      },
      "name1": {
        "type": "string",
        "description": "Name line 1"
      },
      "name2": {
        "type": "string",
        "description": "Name line 2 (attention/care of, etc.)"
      },
      "address1": {
        "type": "string",
        "description": "Address line 1"
      },
      "address2": {
        "type": "string",
        "description": "Address line 2 (apartment, unit, etc.)"
      },
      "city": {
        "type": "string",
        "description": "Address city (not required if international)"
      },
      "state": {
        "type": "string",
        "description": "Address state, abbreviated (not required if international)"
      },
      "postalCode": {
        "type": "string",
        "description": "5 or 5+4 postal code (not required if international)"
      },
      "country": {
        "type": "string",
        "description": "Address country"
      },
      "originalDocumentPath": {
        "type": "string",
        "description": "URI of the rendered letter PDF. S3 objects must be accessible by the `cs_mailhouse_app` IAM account."
      },
      "impressionCount": {
        "type": "number",
        "description": "Number of _sides_ of a piece of paper the letter spans."
      }
    },
    "required": [
      "letterRefId",
      "name1",
      "address1",
      "city",
      "state",
      "postalCode",
      "country",
      "originalDocumentPath",
      "impressionCount"
    ]
  }
}
Response  204
HideShow

The letters have been added to the batch.

Response  404
HideShow

The specified batch does not exist.

Headers
Content-Type: application/json
Body
{
  "message": "Something bad happened"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "The error message"
    }
  }
}
Response  413
HideShow

The request payload contains more than the limit of 1,000 letters per request.

Headers
Content-Type: application/json
Body
{
  "message": "Something bad happened"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "The error message"
    }
  }
}
Response  409
HideShow

The request payload contains enough letters to overfill the specified batch beyond its letterCount, or it contains a letter having a letterRefId which conflicts with a letter previously added to this batch.

Headers
Content-Type: application/json
Body
{
  "message": "One or more letter IDs conflict with existing letters in this batch",
  "conflictingIds": [
    "L0000032",
    "L0001024"
  ]
}
Response  422
HideShow

The request payload contains one or more letters with identical letterRefIds.

Headers
Content-Type: application/json
Body
{
  "message": "One or more letter IDs are identical",
  "duplicateIds": [
    "L0003210",
    "L0005959"
  ]
}

Get tracking status
GET/v2/batches/{batchId}/letters/{letterId}

Retrieves the status of a letter in transit.

Example URI

GET https://csdev-mailhouse-hotfix.azurewebsites.net/v2/batches/ABCD1234/letters/ZYXW9876
URI Parameters
HideShow
batchId
string (required) Example: ABCD1234
letterId
string (required) Example: ZYXW9876
Request  Get tracking status
HideShow
Headers
Content-Type: application/json
Authorization: Bearer <token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
"InTransit"
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "string",
  "enum": [
    "InTransit",
    "Dropped",
    "Accepted",
    "NotMailable",
    "CannotReturnToSender",
    "AwaitingReturn",
    "Returned",
    "Delivered",
    "Other"
  ]
}
Response  404
HideShow

The specified batch or letter could not be found.

Headers
Content-Type: application/json
Body
{
  "message": "Something bad happened"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "The error message"
    }
  }
}

Generated by aglio on 27 Feb 2020