{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"decdaa2f-ec23-443e-b98a-fdb343dee96b","name":"Public API Documentation","description":"This documentation will walk through the Earth Class Mail REST API and present playbooks and use cases for it. If any difficulties arise, please email [api@earthclassmail.com](https://mailto:api@earthclassmail.com) with your questions. We will answer them, provide clarity, and make improvements (to both documentation and APIs) along the way to help you achieve success!\n\n# Authentication\n\nAll requests require a Static API Key for authentication.\n\nStatic API Key can be generated via our ECM web application UI by navigating to:\n\n`Settings` -> `Integrations`\n\nUnder the \"Custom API integration\" section, click \"Generate Key\". This will generate a static GUID that can then be passed in an `x-api-key` header for authentication.\n\n# Request rate-limiting\n\nTo provide all of our customers with the best experience and to maintain a high quality of service, we impose the mandatory request rate limiting.\n\nThe maximum number of requests per minute from a single IP is **300**.\n\nIf you exceed this limit, the API will respond with `429 Too Many Requests` status codes for **5 minutes** from the time the limit was exceeded. This rate limit applies to **all endpoints combined**.\n\n> In general, it's a good practice to code your application in a way that it handles rate limiting, even if you don't expect to hit the limit. \n  \n\n# Paging\n\nMost \"list\" endpoints support paging through the following query string parameters.\n\n- **page** — The desired page from the result set. Integer. Defaults to `1`.\n    \n- **per_page** — The number of items that should be included in a page. Integer. Defaults to `100`.\n    \n\n# Key Concepts\n\n- **Inbox** — A mailbox that receives mail on behalf of a user or organization.\n    \n- **Piece** — An individual item of mail received at a facility and assigned to an Inbox.\n    \n- **Scan** — A request to digitize a Piece. Produces Media items once completed.\n    \n- **Media** — A digital image or PDF associated with a Piece (e.g., envelope photo, content scan). Includes a short-lived download URL.\n    \n- **Shipment** — A request to physically forward one or more Pieces to a Shipping Address.\n    \n- **Shipping Address** — A saved destination address that Pieces can be shipped to.\n    \n- **Shipping Rate** — A real-time carrier quote for a Shipment, including carrier, service, and price.\n    \n\n# Playbooks\n\nThe following is a collection of \"playbooks\" for performing workflows using the Earth Class Mail REST API.\n\n## Retrieve Latest Pieces (with Images)\n\nA typical use case for the ECM REST API would be to retrieve the \"latest\" mail, including the Envelope and Content Scan images. That can be accomplished with the following steps:\n\n1. Retrieve Inboxes available to your user (optional).  \n    If you already know the InboxIds for which you wish to retrieve pieces, you can skip this step. If not, use the [Current User](https://reference.earthclassmail.com/#cb8794ba-75d8-4ee3-9097-685b815a58af) endpoint to retrieve your user ID, and then the [List Inboxes](https://reference.earthclassmail.com/#b149d661-caa6-4165-a262-42bfdd5adcb2) endpoint to retrieve the InboxIds your user has access to.\n    \n2. Retrieve \"recent\" pieces.  \n    The [Inbox Pieces](https://reference.earthclassmail.com/#39f4b4d3-e64e-40ee-817a-4bfe23a9fb4d) endpoint returns a paged list of Pieces for a particular Inbox. By sorting on \"received_at\" and using the \"received_after\" filter, the \"most recent\" pieces can be returned.\n    \n3. Retrieve Piece Media.  \n    Once the list of Pieces has been obtained, invoke the [Get Bulk Piece Media](https://reference.earthclassmail.com/#4a4fa124-3157-4796-b46e-04c903a86494) endpoint. This will return a list of images (both Envelopes and Content Scans) associated with the Piece IDs, along with short-lived URLs for downloading the actual image/PDF files.\n    \n\n## Requesting a Shipment\n\nA typical use case for the ECM REST API is to request that physical mail be shipped to a destination mailing address. That can be accomplished with the following steps:\n\n1. Retrieve Inboxes available to your user (optional).  \n    If you already know the InboxIds for which you wish to retrieve pieces, this step can be skipped. If not, use the [Current User](https://reference.earthclassmail.com/#cb8794ba-75d8-4ee3-9097-685b815a58af) endpoint to retrieve your user ID, and then [List Inboxes](https://reference.earthclassmail.com/#b149d661-caa6-4165-a262-42bfdd5adcb2).\n    \n2. Retrieve \"recent\" Pieces.  \n    The [Inbox Pieces](https://reference.earthclassmail.com/#39f4b4d3-e64e-40ee-817a-4bfe23a9fb4d) endpoint returns a paged list of Pieces for a particular Inbox. By sorting on \"received_at\" and using the \"received_after\" filter, the \"most recent\" pieces can be returned.\n    \n3. Retrieve Shipping Addresses.  \n    If the Shipping Address already exists within Earth Class Mail's system, it can be retrieved by invoking the [Get Shipping Addresses](https://reference.earthclassmail.com/#be871e93-d55a-4f4b-a2e6-94dc35771adb) endpoint. This will return a list of Shipping Addresses associated with the given inboxId.\n    \n4. Retrieve Shipping Rates for items.  \n    With a Shipping Address in place, it's time to retrieve available Rates. These are retrieved in real time from our shipping Providers, and allow you to select the Rate that works best for you. They are retrieved using the [Get Shipping Rates](https://reference.earthclassmail.com/#b0733438-8cb0-48a9-8ae9-8d5c5ac18c54) endpoint.\n    \n5. Create Shipment.  \n    With the desired rate obtained, you can now invoke the [Create Shipment](https://reference.earthclassmail.com/#c53556f1-2c75-408b-9c8f-0b39ed204883) call to create your shipment.\n    \n6. Get Pending Shipments.  \n    The following endpoint can be used to obtain all shipments on your account: [Get Shipments](https://reference.earthclassmail.com/#16838487-9238-47b4-862b-3a8d303c7d96)\n    \n\n## Email Pieces\n\nThe following steps can be used to parse through the latest items in your inbox and email the Scans to an external email address.\n\n1. Retrieve Inboxes available to your user (optional).  \n    If you already know the InboxIds for which you wish to retrieve pieces, this step can be skipped. If not, use the [Current User](https://reference.earthclassmail.com/#cb8794ba-75d8-4ee3-9097-685b815a58af) endpoint to retrieve your user ID, and then [List Inboxes](https://reference.earthclassmail.com/#b149d661-caa6-4165-a262-42bfdd5adcb2).\n    \n2. Retrieve \"recent\" Pieces.  \n    The [Inbox Pieces](https://reference.earthclassmail.com/#39f4b4d3-e64e-40ee-817a-4bfe23a9fb4d) endpoint will return a paged list of Pieces belonging to a particular Inbox. By sorting on \"received_at\" and using the \"received_after\" filter, the \"most recent\" pieces can be returned.\n    \n3. Retrieve Scans for \"scanned\" Pieces.  \n    Each Piece returned by the Pieces endpoint in #2 will have an \"attributes\" property (array), and if the item has been scanned, this array will contain the attribute \"scanned\". This can be used to identify the Pieces ready to email. The scan info can be retrieved with the [Get Piece Scans](https://reference.earthclassmail.com/#59d467a4-8347-4d51-af40-dab287ee4c32) endpoint.\n    \n4. For each Piece you'd like to email, invoke the [Email Scan](https://reference.earthclassmail.com/#fa07470c-d642-4657-bdf7-7a2496bbccbc) endpoint with the following payload:\n    \n    ``` json\n                {\n                    \"emails\": [\n                        \"email@email.com\"\n                    ],\n                    \"comment\": \"here is a scan!\"\n                }\n    \n     ```\n    \n5. Finally, if you'd like this Piece to be archived upon successful emailing, do so with the [Archive Piece](https://reference.earthclassmail.com/#e16faff6-fa43-4848-a9bf-aaba4cc6888b) endpoint.\n    \n\n## Shredding a Piece\n\nTo request that a physical piece of mail be permanently destroyed (shredded), use the Disposal endpoint.\n\n1. Identify the Piece to shred.  \n    Use the [Inbox Pieces](https://reference.earthclassmail.com/#39f4b4d3-e64e-40ee-817a-4bfe23a9fb4d) endpoint to find the Piece ID, or use a Piece ID you already have.\n    \n2. Request Disposal.  \n    Invoke the [Request Piece Shredding](https://reference.earthclassmail.com/#83417671-d627-405e-a607-931cbbaa9f00) endpoint. Optionally set `delete_scans` to `true` if you also want to remove the digital scans associated with the Piece.\n    \n    ``` json\n              {\n               \"delete_scans\": \"true|false\"\n              }\n    \n     ```\n    \n3. Verify Disposal status (optional).  \n    Use the [Get Piece Shredding Details](https://reference.earthclassmail.com/#2064b7b6-7355-4262-9595-e79aad61df0e) endpoint to check the status of the disposal operation.\n    \n4. Cancel Disposal (optional).  \n    If the disposal has not yet been completed, it can be canceled with the [Cancel Pending Piece Shredding](https://reference.earthclassmail.com/#371e4a22-a3b7-4abb-ba2c-5da89b30e542) endpoint. There is a 7-day grace period after the disposal is requested — once this period has passed, the shredding cannot be canceled.\n    \n\n## List Pieces with Detected Checks\n\nTo retrieve pieces where a check has been detected during scanning, use the [Inbox Pieces](https://reference.earthclassmail.com/#39f4b4d3-e64e-40ee-817a-4bfe23a9fb4d) endpoint with the `contains` filter set to `payment-detected`.\n\n```\nGET /inboxes/{inbox_id}/pieces?filters=contains:payment-detected&sort_by=received_at&sort_direction=desc\n\n ```\n\nEach returned Piece will include a `detected_checks_count` field indicating how many checks were found. This can be combined with other filters such as `received_after` to narrow results to recent items.\n\n## Retrieving Check Deposit Details\n\nUse the [Get Check Deposit Requests](https://reference.earthclassmail.com/#ba487d2a-c4a8-45c1-a152-a40e571f0f23) endpoint to retrieve deposit requests for an inbox. Each deposit request includes the `status`, `bank_account`, `checks` found, `deposit_slips` with download URLs, and `requested_at` / `extracted_at` timestamps. Optional filters include `has_checks`, `date_from`, `date_to`, and sorting by `requested_at` or `extracted_at`.\n\nAlternatively, if you already know the Piece ID, use `GET /pieces/{piece_id}/check-deposit-requests` to retrieve deposit requests for that specific piece.","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":true,"owner":"4138716","collectionId":"decdaa2f-ec23-443e-b98a-fdb343dee96b","publishedId":"RWaHzAKJ","public":true,"publicUrl":"https://reference.earthclassmail.com","privateUrl":"https://go.postman.co/documentation/4138716-decdaa2f-ec23-443e-b98a-fdb343dee96b","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"2E95E5"},"documentationLayout":"classic-double-column","customisation":{"metaTags":[{"name":"description","value":""},{"name":"title","value":""}],"appearance":{"default":"light","themes":[{"name":"dark","logo":null,"colors":{"top-bar":"212121","right-sidebar":"303030","highlight":"FF6C37"}},{"name":"light","logo":null,"colors":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"2E95E5"}}]}},"version":"8.12.0","publishDate":"2025-07-21T12:04:36.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"","description":""},"logos":{"logoLight":null,"logoDark":null}},"statusCode":200},"environments":[{"name":"Production","id":"e119181e-2cd0-4321-986c-20ccb153a6d3","owner":"4138716","values":[{"key":"api_root","value":"https://api.earthclassmail.com/v1/","enabled":true,"type":"default"},{"key":"iris_root","value":"https://secure.earthclassmail.com/","enabled":true,"type":"default"},{"key":"api_key","value":null,"enabled":true,"type":"default"}],"published":true}],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/edb5381e5be27ef9670c1cc839545edec4dcace6c7156fba7e36342368712568","favicon":"https://earthclassmail.com/favicon.ico"},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"},{"label":"Production","value":"4138716-e119181e-2cd0-4321-986c-20ccb153a6d3"}],"canonicalUrl":"https://reference.earthclassmail.com/view/metadata/RWaHzAKJ"}