{"openapi":"3.1.0","info":{"title":"Praecise Inbox API","version":"1.0.0","description":"Read, search, change and send mail in the mailboxes an access key was approved for. Keys are issued by a person at /connect, name their mailboxes and permissions, and every call is recorded on the mailbox's Activity page."},"servers":[{"url":"https://email.inbox.praecise.com/api"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"type":"http","scheme":"bearer","description":"An access key beginning pik_"}}},"paths":{"/mailboxes":{"get":{"operationId":"list_mailboxes","summary":"List mailboxes","description":"The mailboxes this key may use, what kind each is, and what the key may do.","parameters":[],"responses":{"200":{"description":"List mailboxes","content":{"application/json":{"schema":{"type":"array","items":{"type":"object"}}}}},"401":{"description":"No valid access key."},"403":{"description":"The key may not do this on this mailbox."},"429":{"description":"Too many calls; see Retry-After."}}}},"/mailboxes/{mailbox}/folders":{"get":{"operationId":"list_folders","summary":"List folders","description":"The folders in a mailbox with unread and total counts.","parameters":[{"name":"mailbox","in":"path","required":true,"schema":{"type":"string"},"description":"Mailbox address."}],"responses":{"200":{"description":"List folders","content":{"application/json":{"schema":{"type":"array","items":{"type":"object"}}}}},"401":{"description":"No valid access key."},"403":{"description":"The key may not do this on this mailbox."},"429":{"description":"Too many calls; see Retry-After."}}}},"/mailboxes/{mailbox}/messages":{"get":{"operationId":"list_messages","summary":"List messages","description":"The newest messages in a folder: sender, subject, date, a snippet, and whether each is unread.","parameters":[{"name":"mailbox","in":"path","required":true,"schema":{"type":"string"},"description":"Mailbox address."},{"name":"folder","in":"query","schema":{"type":"string","default":"inbox"}},{"name":"limit","in":"query","schema":{"type":"integer","maximum":100}},{"name":"q","in":"query","schema":{"type":"string"},"description":"When present, searches across folders instead of listing one."}],"responses":{"200":{"description":"List messages","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"folder":{"type":"string"},"from":{"type":"string"},"to":{"type":"string"},"date":{"type":"string"},"subject":{"type":"string"},"snippet":{"type":"string"},"unread":{"type":"boolean"}},"required":["id","folder"]}}}}},"401":{"description":"No valid access key."},"403":{"description":"The key may not do this on this mailbox."},"429":{"description":"Too many calls; see Retry-After."}}}},"/mailboxes/{mailbox}/messages/{id}":{"get":{"operationId":"get_message","summary":"Read a message","description":"One message as text, with its attachments listed and any order, invoice, delivery or booking the sender declared as structured data. Messages carrying one-time codes are withheld unless the key may read codes.","parameters":[{"name":"mailbox","in":"path","required":true,"schema":{"type":"string"},"description":"Mailbox address."},{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"folder","in":"query","schema":{"type":"string","default":"inbox"}},{"name":"html","in":"query","schema":{"type":"string","enum":["1"]}}],"responses":{"200":{"description":"Read a message","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No valid access key."},"403":{"description":"The key may not do this on this mailbox."},"429":{"description":"Too many calls; see Retry-After."}}}},"/mailboxes/{mailbox}/messages/{id}/read":{"post":{"operationId":"mark_message","summary":"Mark read or unread","description":"Set or clear the read flag on a message.","parameters":[{"name":"mailbox","in":"path","required":true,"schema":{"type":"string"},"description":"Mailbox address."},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Mark read or unread","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No valid access key."},"403":{"description":"The key may not do this on this mailbox."},"429":{"description":"Too many calls; see Retry-After."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"folder":{"type":"string","description":"Folder id: inbox, sent, draft, archive, spam, trash, or a custom folder name.","default":"inbox"},"read":{"type":"boolean","default":true}}}}}}}},"/mailboxes/{mailbox}/messages/{id}/move":{"post":{"operationId":"move_message","summary":"Move a message","description":"Move a message to another folder. Archive and Trash are folders; nothing is deleted outright.","parameters":[{"name":"mailbox","in":"path","required":true,"schema":{"type":"string"},"description":"Mailbox address."},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Move a message","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No valid access key."},"403":{"description":"The key may not do this on this mailbox."},"429":{"description":"Too many calls; see Retry-After."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"folder":{"type":"string","description":"Folder id: inbox, sent, draft, archive, spam, trash, or a custom folder name.","default":"inbox"},"to":{"type":"string","description":"Destination folder, e.g. Archive or Trash."}}}}}}}},"/mailboxes/{mailbox}/send":{"post":{"operationId":"send_message","summary":"Send a message","description":"Send plain-text mail from a mailbox. If this key may only send with approval, the message is held and the result says waiting_for_approval; check send_status later. Never assume a held message was delivered.","parameters":[{"name":"mailbox","in":"path","required":true,"schema":{"type":"string"},"description":"Mailbox address."}],"responses":{"200":{"description":"Send a message","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["sent","waiting_for_approval"]},"id":{"type":["string","null"]},"note":{"type":"string"}},"required":["status"]}}}},"401":{"description":"No valid access key."},"403":{"description":"The key may not do this on this mailbox."},"429":{"description":"Too many calls; see Retry-After."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"to":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":50},"subject":{"type":"string"},"text":{"type":"string"}}}}}}}},"/mailboxes/{mailbox}/purchases":{"get":{"operationId":"list_purchases","summary":"List purchases","description":"Orders, invoices, deliveries and bookings that senders declared in schema.org markup, each linked to the message it came in.","parameters":[{"name":"mailbox","in":"path","required":true,"schema":{"type":"string"},"description":"Mailbox address."},{"name":"kind","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"List purchases","content":{"application/json":{"schema":{"type":"array","items":{"type":"object"}}}}},"401":{"description":"No valid access key."},"403":{"description":"The key may not do this on this mailbox."},"429":{"description":"Too many calls; see Retry-After."}}}},"/sends/{id}":{"get":{"operationId":"send_status","summary":"Check a held message","description":"Whether a message held for approval is still waiting, was sent, or was rejected.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Check a held message","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"No valid access key."},"403":{"description":"The key may not do this on this mailbox."},"429":{"description":"Too many calls; see Retry-After."}}}}}}