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](/v2026-01-15/guides/lockbox-providers/batch-format) specification.
The `location_id` must match the format `po_<number>` (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](/v2026-01-15/guides/lockbox-providers/mail-uploads) 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](/v2026-01-15/guides/lockbox-providers/provisioning) 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:
responses:
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.
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.
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
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.
securitySchemes:
bearerAuth:
type: http
scheme: bearer