Chariot Mailbox API
The mailbox API from Chariot — 2 operation(s) for mailbox.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/chariot-mailbox-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Chariot Mailbox API
version: v1
description: The Chariot REST API. Please see https://docs.givechariot.com/api for more details.
contact:
name: Chariot Development Team
url: https://givechariot.com/contact
email: developers@givechariot.com
termsOfService: https://givechariot.com/legal-nonprofit
servers:
- url: https://sandboxapi.givechariot.com
description: Sandbox
- url: https://api.givechariot.com
description: Production
tags:
- name: Mailbox
paths:
/v1/mailbox/upload_url:
post:
summary: Get a Batch Upload URL
description: 'Returns a presigned URL for uploading a mailbox batch.
A batch is a ZIP file containing TIFF images and a CSV index file.
The CSV must conform to the Batch Format specification.
The `location_id` must match the format `po_` (e.g., `po_543`).
The returned URL is a presigned S3 URL valid for 15 minutes. Upload the batch ZIP file using an HTTP PUT request to this URL.
See the Mail Uploads guide for details on the upload and rescan process.'
operationId: getMailboxUploadUrl
tags:
- Mailbox
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- location_id
properties:
location_id:
type: string
description: The identifier of the PO box or lockbox location. Must match the format `po_<number>`.
example: po_543
responses:
'200':
description: Successfully generated a presigned upload URL.
content:
application/json:
schema:
type: object
properties:
url:
type: string
description: The presigned URL to upload the batch ZIP file to via HTTP PUT. Expires after 15 minutes.
example: https://storage.example.com/upload?token=abc123
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/AuthenticationError'
'403':
$ref: '#/components/responses/ForbiddenError'
'500':
$ref: '#/components/responses/InternalServerError'
/v1/lockboxes/fulfill_request:
post:
summary: Fulfill a Lockbox Request
description: 'Notifies Chariot that a new PO box has been provisioned by the lockbox provider.
The `request_id` is a one-time unique value generated by Chariot for each PO box request.
See the Provisioning guide for the full provisioning flow.'
operationId: provisionMailbox
tags:
- Mailbox
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- request_id
- location_id
- address
properties:
request_id:
type: string
description: The unique request identifier originally provided by Chariot when the PO box was requested.
example: '123456789'
location_id:
type: string
description: The identifier of the newly provisioned PO box.
example: po_9876
address:
$ref: '#/components/schemas/Address'
responses:
'200':
description: Indicates the PO box has been successfully provisioned.
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/AuthenticationError'
'403':
$ref: '#/components/responses/ForbiddenError'
'500':
$ref: '#/components/responses/InternalServerError'
components:
schemas:
Address:
type: object
required:
- city
- country
- line1
- postal_code
- state
properties:
city:
type: string
description: 'City, district, suburb, town, or village. Maximum length: 255 characters.'
example: New York
country:
type: string
description: Two-letter country code (https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
example: US
line1:
type: string
description: 'Address line 1 (e.g. street, PO Box, or company name). Maximum length: 255 characters.'
example: 123 Main St.
line2:
type: string
description: 'Address line 2 (e.g. apartment, suite, unit, or building). Maximum length: 255 characters.'
postal_code:
type: string
description: 'ZIP or postal code. Maximum length: 40 characters.'
example: '12345'
state:
type: string
description: State, county, province, or region
example: NY
ProblemDetails:
type: object
description: RFC 7807 problem-details error (media type application/problem+json). The `status` field is an integer HTTP status code.
required:
- type
- title
- status
- detail
properties:
type:
type: string
description: A URI reference identifying the problem type.
example: about:blank
title:
type: string
description: A short, human-readable summary of the problem type.
example: API Error
status:
type: integer
description: The HTTP status code for this error.
example: 400
detail:
type: string
description: A human-readable explanation specific to this occurrence.
example: The request is invalid or contains invalid parameters.
example:
type: about:blank
title: API Error
status: 400
detail: The request is invalid or contains invalid parameters.
responses:
AuthenticationError:
description: Unauthorized. The request is missing the security (OAuth2 Bearer token) requirements and the server is unable to verify the identify of the caller.
headers:
X-Request-Id:
$ref: '#/components/headers/X-Request-Id'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
examples:
Unauthorized:
value:
type: about:blank
title: API Error
status: 401
detail: Authentication credentials were missing or invalid.
ForbiddenError:
description: Access denied
headers:
X-Request-Id:
$ref: '#/components/headers/X-Request-Id'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
examples:
Forbidden:
value:
type: about:blank
title: API Error
status: 403
detail: You do not have permission to access this resource.
BadRequestError:
description: The request is invalid or contains invalid parameters
headers:
X-Request-Id:
$ref: '#/components/headers/X-Request-Id'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
examples:
BadRequest:
value:
type: about:blank
title: API Error
status: 400
detail: The request is invalid or contains invalid parameters.
InternalServerError:
description: Internal Server Error
headers:
X-Request-Id:
$ref: '#/components/headers/X-Request-Id'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'
examples:
InternalServerError:
value:
type: about:blank
title: API Error
status: 500
detail: The server encountered an error processing your request.
headers:
X-Request-Id:
description: The unique identifier for the request
schema:
type: string
securitySchemes:
bearerAuth:
type: http
scheme: bearer