{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"decdaa2f-ec23-443e-b98a-fdb343dee96b","name":"Public API Documentation","description":"This documentation will walk through the Earthclassmail REST API, and present playbooks and possibilities for using the API. This is the same API we use within our Web and Mobile UIs, so in general, anything you can do with our UI, you can also do with our REST API.\n\nIf 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 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 in lieu of the transient JWT token mentioned above.\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 allowed amount of requests from one IP is set to **300 requests per minute**.\n\nIf you exceed this amount, all future requests will be automatically terminated before reaching any of our endpoints. This will continue for **5 minutes** from the time the request limit was exceeded.\n\n###### Note\n\n> In general, it's a good practice to code your application in a way that it will handle that kind of request rate limiting, even if you don't suspect it will occur. \n  \n\n## Calculation of requests\n\nPlease note this is a fixed rate limit calculated for **all of our endpoints combined**.\n\n###### Example\n\n> During the last minute, you have made: \n  \n\n# Paging\n\nMost \"list\" endpoints support paging, through the following query string parameters.\n\n## page\n\nThe desired page from the result set.\n\nInteger. Defaults to `1`.\n\n## per_page\n\nThe number of items that should be included in a page.\n\nInteger. Defaults to `100`.\n\n# Playbooks\n\nThe following is a collection of \"playbooks\" that can be used to perform a workflow 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)If you already know the InboxIds you wish to retrieve pieces for, this step can be skipped. If not, use the  \n    [Current User<br>](https://www.postman.com/earthclass/workspace/earth-class-mail-s-public-workspace/request/4138716-cb8794ba-75d8-4ee3-9097-685b815a58af?action=share&source=copy-link&creator=18183029&ctx=documentation)endpoint to retrieve your user ID, and then\n    \n    <a href=\"https://reference.earthclassmail.com/?version=latest#b149d661-caa6-4165-a262-42bfdd5adcb2\">List Inboxes</a>\n    \n    endpoint to retrieve the InboxIds your user has access to.\n    \n2. Retrieve \"recent\" pieces. The\n    \n    <a href=\"https://reference.earthclassmail.com/?version=latest#39f4b4d3-e64e-40ee-817a-4bfe23a9fb4d\">Inbox Pieces</a>\n    \n    endpoint will return a paged list of Pieces belonging to a particular Inbox. With a combination of Sorting on \"received_at\", and the \"received_after\" filter, the \"most recent\" pieces can be returned. Here's an example of what that URL might look like:\n    \n3. Retrieve Piece Media  \n    Once the list of Pieces has been obtained, invoke the\n    \n    <a href=\"https://reference.earthclassmail.com/?version=latest#4a4fa124-3157-4796-b46e-04c903a86494\">Get Bulk Piece Media</a>\n    \n    endpoint. This will return a list of images (both Envelopes and Content Scans) associated with the Piece Ids, as well as short-lived URLs that can be used to download the actual image/PDF files.\n    \n\n## Requesting a Shipment\n\nA typical use case for the ECM REST API would be to request physical mail to be shipped to a destination mailing address. That can be accomplished with the following steps:\n\n1. Retrieve Inboxes available to your user (optional)If you already know the InboxIds you wish to retrieve pieces for, this step can be skipped. If not, use the  \n    [Current User<br>](https://www.postman.com/earthclass/workspace/earth-class-mail-s-public-workspace/request/4138716-cb8794ba-75d8-4ee3-9097-685b815a58af?action=share&source=copy-link&creator=18183029&ctx=documentation)endpoint to retrieve your user ID, and then\n    \n    <a href=\"https://reference.earthclassmail.com/?version=latest#b149d661-caa6-4165-a262-42bfdd5adcb2\">List Inboxes</a>\n    \n2. Retrieve \"recent\" Pieces. The\n    \n    <a href=\"https://reference.earthclassmail.com/?version=latest#39f4b4d3-e64e-40ee-817a-4bfe23a9fb4d\">Inbox Pieces</a>\n    \n    endpoint will return a paged list of Pieces belonging to a particular Inbox. With a combination of Sorting on \"received_at\", and the \"received_after\" filter, the \"most recent\" pieces can be returned. Here's an example of what that URL might look like:\n    \n3. Retrieve Shipping AddressesIf the Shipping Address already exists within Earth Class Mail's system, it can be retrieved by invoking the\n    \n    <a href=\"https://reference.earthclassmail.com/?version=latest#be871e93-d55a-4f4b-a2e6-94dc35771adb\">Get Shipping Addresses</a>\n    \n    endpoint. This will return a list of Shipping Addresses associated with the given inboxId.\n    \n4. Retrieve Shipping Rates for itemsWith 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\n    \n    <a href=\"https://reference.earthclassmail.com/?version=latest#b0733438-8cb0-48a9-8ae9-8d5c5ac18c54\">Get Shipping Rates</a>\n    \n    endpoint (note that even though this loosely referred to with \"Get\", it is a Post operation).\n    \n5. Create ShipmentWith the desired rate obtained, you can now invoke the\n    \n    <a href=\"https://reference.earthclassmail.com/?version=latest#c53556f1-2c75-408b-9c8f-0b39ed204883\">Create Shipment</a>\n    \n    call to create your Shipment.\n    \n6. Get Pending Shipments  \n    The following endpoint can be used to obtain all shipments on your account:\n    \n    <a href=\"https://reference.earthclassmail.com/?version=latest#16838487-9238-47b4-862b-3a8d303c7d96\">Get Shipments</a>\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)If you already know the InboxIds you wish to retrieve pieces for, this step can be skipped. If not, use the  \n    [Current User<br>](https://www.postman.com/earthclass/workspace/earth-class-mail-s-public-workspace/request/4138716-cb8794ba-75d8-4ee3-9097-685b815a58af?action=share&source=copy-link&creator=18183029&ctx=documentation)endpoint to retrieve your user ID, and then\n    \n    <a href=\"https://reference.earthclassmail.com/?version=latest#b149d661-caa6-4165-a262-42bfdd5adcb2\">List Inboxes</a>\n    \n2. Retrieve \"recent\" Pieces. The\n    \n    <a href=\"https://reference.earthclassmail.com/?version=latest#39f4b4d3-e64e-40ee-817a-4bfe23a9fb4d\">Inbox Pieces</a>\n    \n    endpoint will return a paged list of Pieces belonging to a particular Inbox. With a combination of Sorting on \"received_at\", and the \"received_after\" filter, the \"most recent\" pieces can be returned. Here's an example of what that URL might look like:\n    \n3. Retrieve Scans for \"scanned\" Pieces.Each Piece returned by the Pieces endpoint in #4 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 following endpoint:\n    \n    ```\n                        https://api.earthclassmail.com/v1/pieces/<pieceId>>/scans\n    \n     ```\n    \n4. For each Piece you'd like to email, invoke the following endpoint:\n    \n    ```\n                        POST https://api.earthclassmail.com/v1/scans/{ScanId}/email\n    \n     ```\n    \n    With the following payload:\n    \n    ```\n                        {\"emails\":[\"email@email.com\"],\"comment\":\"here is a scan!\"}\n    \n     ```\n    \n5. Finally, if you'd like this Piece to be archived upon successful emailing, do so with the following endpoint:\n    \n    ```\n                        POST https://api.earthclassmail.com/v1/pieces/{PieceId}/archive\n    \n     ```","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.10.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":[{"value":"https://api.earthclassmail.com/v1/","key":"api_root","enabled":true},{"value":"https://secure.earthclassmail.com/","key":"iris_root","enabled":true},{"value":null,"key":"ecm_access_token","enabled":true},{"value":null,"key":"ecm_refresh_token","enabled":true}],"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"}