{"openapi":"3.1.0","info":{"title":"Innbocks Partner API","version":"1.0.0","description":"Versioned REST API for CRM, billing, mailbox operations, compliance state, mail actions, webhooks, and usage reconciliation. Authenticate with a scoped `ib_live_` bearer key created in the dashboard. Human-readable docs: https://www.innbocks.com/developers","contact":{"name":"Innbocks Partnerships","url":"https://www.innbocks.com/developers"},"termsOfService":"https://www.innbocks.com/terms"},"externalDocs":{"description":"Developer documentation","url":"https://www.innbocks.com/developers"},"servers":[{"url":"https://www.innbocks.com","description":"Production"}],"tags":[{"name":"Customers","description":"Provision and manage mailbox renters."},{"name":"Mailboxes","description":"Mailbox assignment and availability."},{"name":"Mail","description":"Inbound mail/package records and items."},{"name":"Mail actions","description":"Request scan, forward, shred, and pickup."},{"name":"Compliance","description":"USPS Form 1583 and ID verification state."},{"name":"Webhooks","description":"Outbound event types and delivery history."},{"name":"Billing","description":"Active-mailbox usage reconciliation."}],"components":{"securitySchemes":{"partnerApiKey":{"type":"http","scheme":"bearer","bearerFormat":"ib_live API key","description":"Send `Authorization: Bearer ib_live_...`. Keys are scoped; each operation lists its required scope under `x-required-scopes`."}},"schemas":{"Scope":{"type":"string","enum":["customers:read","customers:write","mail:read","mail:write","mail_actions:write","webhooks:read","billing:read"]},"WebhookEvent":{"type":"string","enum":["customer.created","customer.activated","customer.verified","customer.form_1583_status_updated","webhook.test","mail.arrived","package.arrived","mail.scan_requested","mail.scanned","mail.forward_requested","mail.forwarded","mail.pickup_requested","mail.pickup_scheduled","mail.picked_up","mail.shred_requested","mail.shredded","limited.reached.scans","limited.reached.shreds","limited.reached.pickups"]},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","example":"not_found"},"message":{"type":"string"},"request_id":{"type":"string"}}}}},"Customer":{"type":"object","properties":{"id":{"type":"string"},"external_customer_id":{"type":"string","nullable":true},"email":{"type":"string","format":"email"},"name":{"type":"string"},"phone":{"type":"string","nullable":true},"status":{"type":"string"},"is_active":{"type":"boolean"},"prepay":{"type":"boolean"},"box_number":{"type":"string","nullable":true},"pmb":{"type":"string","nullable":true},"mailbox_id":{"type":"string","nullable":true},"mailbox_active":{"type":"boolean"},"plan":{"type":"object","properties":{"id":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"price_cents":{"type":"integer","nullable":true}}},"form_1583_status":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time","nullable":true},"updated_at":{"type":"string","format":"date-time","nullable":true}}},"Mailbox":{"type":"object","properties":{"customer_id":{"type":"string"},"mailbox_id":{"type":"string","nullable":true},"box_number":{"type":"string","nullable":true},"pmb":{"type":"string","nullable":true},"assignment_mode":{"type":"string"},"rendered_address":{"type":"string","nullable":true},"mailbox_active":{"type":"boolean"}}},"AvailableMailbox":{"type":"object","properties":{"id":{"type":"string"},"box_number":{"type":"string"},"type":{"type":"string","nullable":true},"size":{"type":"string","nullable":true},"status":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Mail":{"type":"object","properties":{"id":{"type":"string"},"customer_id":{"type":"string"},"type":{"type":"string"},"status":{"type":"string"},"old_status":{"type":"string","nullable":true},"processed_status":{"type":"string","nullable":true},"request_status":{"type":"array","items":{"type":"string"}},"mail_number":{"type":"string","nullable":true},"box_number":{"type":"string","nullable":true},"image_url":{"type":"string","format":"uri","nullable":true},"photo_urls":{"type":"array","items":{"type":"string","format":"uri"}},"pdf_url":{"type":"string","format":"uri","nullable":true},"description":{"type":"string","nullable":true},"performed_by":{"type":"string","nullable":true},"source":{"type":"string","nullable":true},"mailbox_id":{"type":"string","nullable":true},"scan_available":{"type":"boolean"},"forwarding":{"type":"object","properties":{"shipping_address":{"type":"string","nullable":true},"shipping_method":{"type":"string","nullable":true},"tracking_number":{"type":"string","nullable":true},"shipping_company":{"type":"string","nullable":true}}},"pickup":{"type":"object","properties":{"pickup_date":{"type":"string","nullable":true},"pickup_time":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true}}},"created_at":{"type":"string","format":"date-time","nullable":true},"updated_at":{"type":"string","format":"date-time","nullable":true}}},"ServiceRequest":{"type":"object","description":"A queued operator work item created by a mail-action request.","properties":{"id":{"type":"string"},"mail_id":{"type":"string","nullable":true},"customer_id":{"type":"string"},"type":{"type":"string"},"status":{"type":"string"},"amount_cents":{"type":"integer"},"billing_status":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time","nullable":true},"updated_at":{"type":"string","format":"date-time","nullable":true}}},"Compliance":{"type":"object","properties":{"customer_id":{"type":"string"},"form_1583_status":{"type":"string"},"id_status":{"type":"string","enum":["verified","submitted","not_submitted"]},"notary_status":{"type":"string"},"mailbox_active":{"type":"boolean"},"verified_in_person":{"type":"boolean"},"reviewed_at":{"type":"string","format":"date-time","nullable":true},"reviewed_by":{"type":"string","nullable":true},"approved_at":{"type":"string","format":"date-time","nullable":true},"rejection_reason":{"type":"string","nullable":true},"photo_id_expires_at":{"type":"string","format":"date-time","nullable":true},"address_id_expires_at":{"type":"string","format":"date-time","nullable":true}}},"WebhookDelivery":{"type":"object","properties":{"id":{"type":"string"},"endpoint_id":{"type":"string"},"event_id":{"type":"string"},"event_type":{"$ref":"#/components/schemas/WebhookEvent"},"payload":{"type":"object","additionalProperties":true},"status":{"type":"string"},"attempt_count":{"type":"integer"},"next_attempt_at":{"type":"string","format":"date-time","nullable":true},"last_attempt_at":{"type":"string","format":"date-time","nullable":true},"delivered_at":{"type":"string","format":"date-time","nullable":true},"response_status":{"type":"integer","nullable":true},"response_body":{"type":"string","nullable":true},"error":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"}}},"Usage":{"type":"object","properties":{"period_start":{"type":"string","format":"date-time"},"period_end":{"type":"string","format":"date-time"},"active_mailboxes":{"type":"integer"},"platform_fee_cents_per_mailbox":{"type":"integer"},"estimated_platform_fee_cents":{"type":"integer"},"customers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string","format":"email"},"name":{"type":"string"},"status":{"type":"string"},"box_number":{"type":"string","nullable":true},"prepay":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}}}}}}}},"security":[{"partnerApiKey":[]}],"paths":{"/api/v1/customers":{"get":{"tags":["Customers"],"security":[{"partnerApiKey":[]}],"summary":"List customers","description":"Requires the `customers:read` scope.","x-required-scopes":["customers:read"],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","description":"Pagination cursor from a previous response's `next_cursor`.","schema":{"type":"string"}},{"name":"email","in":"query","schema":{"type":"string"}},{"name":"external_customer_id","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string"}},{"name":"box_number","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Customers","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"customers":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}},"next_cursor":{"type":"string","nullable":true}}}}}}}},"401":{"description":"Missing, invalid, or insufficiently-scoped API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"tags":["Customers"],"security":[{"partnerApiKey":[]}],"summary":"Create invited customer","description":"Requires the `customers:write` scope. Sends the customer an invite to activate their mailbox.","x-required-scopes":["customers:write"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Client-generated key to make retries of this write safe.","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["email","name","phone"],"properties":{"external_customer_id":{"type":"string"},"email":{"type":"string","format":"email"},"name":{"type":"string"},"phone":{"type":"string"},"prepay":{"type":"boolean"},"selected_mailbox_id":{"type":"string"},"plan_id":{"type":"string"}},"example":{"external_customer_id":"crm_customer_123","email":"jane@example.com","name":"Jane Smith","phone":"+15555555555","prepay":true}}}}},"responses":{"201":{"description":"Customer created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"customer":{"$ref":"#/components/schemas/Customer"},"mailbox":{"type":"object","properties":{"box_number":{"type":"string","nullable":true},"mailbox_id":{"type":"string","nullable":true}}},"invite":{"type":"object","properties":{"sent":{"type":"boolean"},"activation_url":{"type":"string","format":"uri"},"token_expires_in":{"type":"integer"}}}}}}}}}},"400":{"description":"Invalid or malformed request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or insufficiently-scoped API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Idempotency key reused with a different payload, or state conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/customers/{customer_id}":{"get":{"tags":["Customers"],"security":[{"partnerApiKey":[]}],"summary":"Retrieve customer","description":"Requires the `customers:read` scope.","x-required-scopes":["customers:read"],"parameters":[{"name":"customer_id","in":"path","required":true,"description":"Innbocks customer id, or your external id when `id_type=external`.","schema":{"type":"string"}},{"name":"id_type","in":"query","required":false,"description":"Set to `external` to resolve the path id against your external_customer_id.","schema":{"type":"string","enum":["external"]}}],"responses":{"200":{"description":"Customer","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Customer"}}}}}},"401":{"description":"Missing, invalid, or insufficiently-scoped API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Customers"],"security":[{"partnerApiKey":[]}],"summary":"Update customer","description":"Requires the `customers:write` scope.","x-required-scopes":["customers:write"],"parameters":[{"name":"customer_id","in":"path","required":true,"description":"Innbocks customer id, or your external id when `id_type=external`.","schema":{"type":"string"}},{"name":"id_type","in":"query","required":false,"description":"Set to `external` to resolve the path id against your external_customer_id.","schema":{"type":"string","enum":["external"]}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Client-generated key to make retries of this write safe.","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"phone":{"type":"string"},"prepay":{"type":"boolean"},"plan_id":{"type":"string","nullable":true},"external_customer_id":{"type":"string","nullable":true}}}}}},"responses":{"200":{"description":"Customer updated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Customer"}}}}}},"400":{"description":"Invalid or malformed request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or insufficiently-scoped API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Idempotency key reused with a different payload, or state conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/customers/{customer_id}/deactivate":{"post":{"tags":["Customers"],"security":[{"partnerApiKey":[]}],"summary":"Deactivate customer","description":"Requires the `customers:write` scope.","x-required-scopes":["customers:write"],"parameters":[{"name":"customer_id","in":"path","required":true,"description":"Innbocks customer id, or your external id when `id_type=external`.","schema":{"type":"string"}},{"name":"id_type","in":"query","required":false,"description":"Set to `external` to resolve the path id against your external_customer_id.","schema":{"type":"string","enum":["external"]}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Client-generated key to make retries of this write safe.","schema":{"type":"string"}}],"responses":{"200":{"description":"Customer deactivated","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Customer"}}}}}},"401":{"description":"Missing, invalid, or insufficiently-scoped API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Idempotency key reused with a different payload, or state conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/customers/{customer_id}/mailbox":{"get":{"tags":["Mailboxes"],"security":[{"partnerApiKey":[]}],"summary":"Retrieve mailbox assignment","description":"Requires the `customers:read` scope.","x-required-scopes":["customers:read"],"parameters":[{"name":"customer_id","in":"path","required":true,"description":"Innbocks customer id, or your external id when `id_type=external`.","schema":{"type":"string"}},{"name":"id_type","in":"query","required":false,"description":"Set to `external` to resolve the path id against your external_customer_id.","schema":{"type":"string","enum":["external"]}}],"responses":{"200":{"description":"Mailbox","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Mailbox"}}}}}},"401":{"description":"Missing, invalid, or insufficiently-scoped API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/customers/{customer_id}/compliance":{"get":{"tags":["Compliance"],"security":[{"partnerApiKey":[]}],"summary":"Retrieve compliance status","description":"Requires the `customers:read` scope. Returns Form 1583, ID, and notary state.","x-required-scopes":["customers:read"],"parameters":[{"name":"customer_id","in":"path","required":true,"description":"Innbocks customer id, or your external id when `id_type=external`.","schema":{"type":"string"}},{"name":"id_type","in":"query","required":false,"description":"Set to `external` to resolve the path id against your external_customer_id.","schema":{"type":"string","enum":["external"]}}],"responses":{"200":{"description":"Compliance","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Compliance"}}}}}},"401":{"description":"Missing, invalid, or insufficiently-scoped API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/customers/{customer_id}/mail":{"get":{"tags":["Mail"],"security":[{"partnerApiKey":[]}],"summary":"List customer mail","description":"Requires the `mail:read` scope.","x-required-scopes":["mail:read"],"parameters":[{"name":"customer_id","in":"path","required":true,"description":"Innbocks customer id, or your external id when `id_type=external`.","schema":{"type":"string"}},{"name":"id_type","in":"query","required":false,"description":"Set to `external` to resolve the path id against your external_customer_id.","schema":{"type":"string","enum":["external"]}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200}},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string"}},{"name":"type","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Mail list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"mail":{"type":"array","items":{"$ref":"#/components/schemas/Mail"}},"next_cursor":{"type":"string","nullable":true}}}}}}}},"401":{"description":"Missing, invalid, or insufficiently-scoped API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/mailboxes/available":{"get":{"tags":["Mailboxes"],"security":[{"partnerApiKey":[]}],"summary":"List available precreated mailboxes","description":"Requires the `customers:read` scope. Only returns mailboxes when the vendor uses precreated assignment.","x-required-scopes":["customers:read"],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","description":"Pagination cursor from a previous response's `next_cursor`.","schema":{"type":"string"}}],"responses":{"200":{"description":"Available mailboxes","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"mailboxes":{"type":"array","items":{"$ref":"#/components/schemas/AvailableMailbox"}},"next_cursor":{"type":"string","nullable":true},"assignment_mode":{"type":"string"}}}}}}}},"401":{"description":"Missing, invalid, or insufficiently-scoped API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/mail/{mail_id}":{"get":{"tags":["Mail"],"security":[{"partnerApiKey":[]}],"summary":"Retrieve mail item","description":"Requires the `mail:read` scope. Image/PDF URLs are short-lived presigned links.","x-required-scopes":["mail:read"],"parameters":[{"name":"mail_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Mail item","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Mail"}}}}}},"401":{"description":"Missing, invalid, or insufficiently-scoped API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Mail"],"security":[{"partnerApiKey":[]}],"summary":"Delete partner-created mail item","description":"Requires the `mail:write` scope. Only mail your integration created can be deleted.","x-required-scopes":["mail:write"],"parameters":[{"name":"mail_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Client-generated key to make retries of this write safe.","schema":{"type":"string"}}],"responses":{"200":{"description":"Mail item deleted","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"deleted":{"type":"boolean"},"mail":{"$ref":"#/components/schemas/Mail"}}}}}}}},"401":{"description":"Missing, invalid, or insufficiently-scoped API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Mail item was not created by your integration","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Idempotency key reused with a different payload, or state conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/mail":{"post":{"tags":["Mail"],"security":[{"partnerApiKey":[]}],"summary":"Create inbound mail or package","description":"Requires the `mail:write` scope. Innbocks verifies the customer belongs to you, has active billing/prepay, and an active/compliant mailbox before emitting `mail.arrived`/`package.arrived`.","x-required-scopes":["mail:write"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Client-generated key to make retries of this write safe.","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["customer_id","type","photos","performed_by"],"properties":{"customer_id":{"type":"string"},"type":{"type":"string","enum":["letter","large_envelope","flat","package","certified","check","legal_mail"]},"photos":{"type":"array","minItems":1,"items":{"type":"string","format":"uri"}},"performed_by":{"type":"string","description":"Partner personnel/operator identifier for custody tracking."},"description":{"type":"string"},"tracking_number":{"type":"string"},"received_at":{"type":"string","format":"date-time"}},"example":{"customer_id":"cus_123","type":"package","photos":["https://example.com/package-front.jpg"],"performed_by":"warehouse_user_42","tracking_number":"1Z9999999999999999"}}}}},"responses":{"201":{"description":"Mail created","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Mail"}}}}}},"400":{"description":"Invalid or malformed request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or insufficiently-scoped API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Idempotency key reused with a different payload, or state conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/mail/{mail_id}/scan":{"post":{"tags":["Mail actions"],"security":[{"partnerApiKey":[]}],"summary":"Request scan","description":"Requires the `mail_actions:write` scope. Creates a scan service request for an operator to fulfill.","x-required-scopes":["mail_actions:write"],"parameters":[{"name":"mail_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Client-generated key to make retries of this write safe.","schema":{"type":"string"}}],"responses":{"202":{"description":"Request accepted","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"action":{"$ref":"#/components/schemas/ServiceRequest"},"mail":{"$ref":"#/components/schemas/Mail"}}}}}}}},"400":{"description":"Invalid or malformed request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or insufficiently-scoped API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Idempotency key reused with a different payload, or state conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/mail/{mail_id}/forward":{"post":{"tags":["Mail actions"],"security":[{"partnerApiKey":[]}],"summary":"Request forwarding","description":"Requires the `mail_actions:write` scope. Creates a forward service request for an operator to fulfill.","x-required-scopes":["mail_actions:write"],"parameters":[{"name":"mail_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Client-generated key to make retries of this write safe.","schema":{"type":"string"}}],"responses":{"202":{"description":"Request accepted","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"action":{"$ref":"#/components/schemas/ServiceRequest"},"mail":{"$ref":"#/components/schemas/Mail"}}}}}}}},"400":{"description":"Invalid or malformed request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or insufficiently-scoped API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Idempotency key reused with a different payload, or state conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/mail/{mail_id}/shred":{"post":{"tags":["Mail actions"],"security":[{"partnerApiKey":[]}],"summary":"Request shredding","description":"Requires the `mail_actions:write` scope. Creates a shred service request for an operator to fulfill.","x-required-scopes":["mail_actions:write"],"parameters":[{"name":"mail_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Client-generated key to make retries of this write safe.","schema":{"type":"string"}}],"responses":{"202":{"description":"Request accepted","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"action":{"$ref":"#/components/schemas/ServiceRequest"},"mail":{"$ref":"#/components/schemas/Mail"}}}}}}}},"400":{"description":"Invalid or malformed request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or insufficiently-scoped API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Idempotency key reused with a different payload, or state conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/mail/{mail_id}/pickup":{"post":{"tags":["Mail actions"],"security":[{"partnerApiKey":[]}],"summary":"Request pickup","description":"Requires the `mail_actions:write` scope. Creates a pickup service request for an operator to fulfill.","x-required-scopes":["mail_actions:write"],"parameters":[{"name":"mail_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Client-generated key to make retries of this write safe.","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["pickup_date","pickup_time"],"properties":{"pickup_date":{"type":"string"},"pickup_time":{"type":"string"},"notes":{"type":"string"}}}}}},"responses":{"202":{"description":"Request accepted","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"action":{"$ref":"#/components/schemas/ServiceRequest"},"mail":{"$ref":"#/components/schemas/Mail"}}}}}}}},"400":{"description":"Invalid or malformed request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid, or insufficiently-scoped API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Idempotency key reused with a different payload, or state conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/webhook-events":{"get":{"tags":["Webhooks"],"security":[{"partnerApiKey":[]}],"summary":"List webhook event types","description":"Requires the `webhooks:read` scope.","x-required-scopes":["webhooks:read"],"responses":{"200":{"description":"Webhook events","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEvent"}},"endpoint_management":{"type":"object","properties":{"mode":{"type":"string"},"path":{"type":"string"}}}}}}}}}},"401":{"description":"Missing, invalid, or insufficiently-scoped API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/webhook-deliveries":{"get":{"tags":["Webhooks"],"security":[{"partnerApiKey":[]}],"summary":"List webhook deliveries","description":"Requires the `webhooks:read` scope.","x-required-scopes":["webhooks:read"],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","description":"Pagination cursor from a previous response's `next_cursor`.","schema":{"type":"string"}},{"name":"event_type","in":"query","schema":{"$ref":"#/components/schemas/WebhookEvent"}},{"name":"status","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Webhook deliveries","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"deliveries":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"}},"next_cursor":{"type":"string","nullable":true}}}}}}}},"401":{"description":"Missing, invalid, or insufficiently-scoped API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/billing/usage":{"get":{"tags":["Billing"],"security":[{"partnerApiKey":[]}],"summary":"Read active mailbox usage","description":"Requires the `billing:read` scope. Returns active mailbox count and estimated platform fee for the current period.","x-required-scopes":["billing:read"],"responses":{"200":{"description":"Usage","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Usage"}}}}}},"401":{"description":"Missing, invalid, or insufficiently-scoped API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}