{"openapi":"3.1.0","x-service-info":{"categories":["email","developer-tools","agents"],"docs":{"homepage":"https://machineinbox.com","apiReference":"https://machineinbox.com/openapi.json","llms":"https://machineinbox.com/llms.txt"}},"info":{"title":"Machine Inbox API","version":"0.1.0","description":"Live Stripe Machine Payments Protocol (MPP). Create short-lived email inboxes for agents, receive mail, and reply inside existing threads.","x-guidance":"Use an MPP-compatible client to POST /api/v1/inboxes. The HTTP 402 WWW-Authenticate challenge offers stripe/charge; retry with Authorization: Payment. Save the returned inbox ID and bearer token. Replies are included.","contact":{"email":"info@machineinbox.com"},"license":{"name":"Commercial API Terms","url":"https://machineinbox.com/terms.html"}},"externalDocs":{"description":"Agent-oriented plain-text instructions","url":"https://machineinbox.com/llms.txt"},"servers":[{"url":"https://machineinbox.com","description":"Live Stripe Machine Payments Protocol (MPP)"}],"tags":[{"name":"Inboxes"},{"name":"Messages"}],"paths":{"/api/v1/inboxes":{"post":{"tags":["Inboxes"],"operationId":"createInbox","summary":"Create an inbox with Stripe MPP: $2.00 for seven days or $5.00 for the thirty-day pro tier; replies included","security":[],"x-payment-info":{"amount":"200","currency":"usd","description":"Machine Inbox - seven-day inbox with replies included","intent":"charge","method":"stripe","methodDetails":{"networkId":"profile_61VF0AQCf2K2etTtBA6VF0AQ2PSQ6DXu7LE66rI6y8ES","paymentMethodTypes":["card","link"]},"protocols":["mpp","x402"],"price":"$2.00","minPrice":"$2.00","maxPrice":"$5.00"},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"product":{"type":"string","enum":["seven_day_inbox","pro_inbox"],"default":"seven_day_inbox","description":"Omit for the standard seven-day inbox; pro_inbox lasts thirty days with higher quotas."}}}}}},"responses":{"201":{"description":"Inbox created. The bearer token is returned once; authenticated replies are included.","headers":{"Payment-Receipt":{"required":true,"description":"MPP receipt for the successful Stripe payment.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInboxResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"402":{"description":"Stripe payment is required via the Machine Payments Protocol (MPP).","headers":{"WWW-Authenticate":{"required":true,"description":"MPP Payment challenge. Retry with the corresponding Authorization: Payment credential.","schema":{"type":"string","pattern":"^Payment "}}}},"409":{"$ref":"#/components/responses/Conflict"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/TemporarilyUnavailable"}}}},"/api/v1/inboxes/{inboxId}":{"get":{"tags":["Inboxes"],"operationId":"getInbox","security":[{"mailboxToken":[]}],"parameters":[{"$ref":"#/components/parameters/InboxId"}],"responses":{"200":{"description":"Inbox state, limits, and current usage.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MailboxResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"410":{"$ref":"#/components/responses/Gone"},"429":{"$ref":"#/components/responses/RateLimited"}}},"delete":{"tags":["Inboxes"],"operationId":"deleteInbox","security":[{"mailboxToken":[]}],"parameters":[{"$ref":"#/components/parameters/InboxId"}],"responses":{"202":{"description":"Token revoked and content deletion queued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteInboxResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"410":{"$ref":"#/components/responses/Gone"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/inboxes/{inboxId}/extend":{"post":{"tags":["Inboxes"],"operationId":"extendInbox","summary":"Extend an active inbox by seven days with Stripe MPP for $1.00","description":"Adds seven days to the current expiry. The mailbox token goes in the X-Mailbox-Token header because Authorization carries the MPP Payment credential on the paid retry. An inbox can never live more than 35 days into the future, and an expired inbox cannot be extended - extend at least ten minutes before expiry.","security":[],"x-payment-info":{"amount":"100","currency":"usd","description":"Machine Inbox - extend an active inbox by seven days","intent":"charge","method":"stripe","methodDetails":{"networkId":"profile_61VF0AQCf2K2etTtBA6VF0AQ2PSQ6DXu7LE66rI6y8ES","paymentMethodTypes":["card","link"]},"protocols":["mpp","x402"],"price":"$1.00"},"parameters":[{"$ref":"#/components/parameters/InboxId"},{"$ref":"#/components/parameters/MailboxTokenHeader"},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"Extension applied; the new expiry is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExtendInboxResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"Stripe payment is required via the Machine Payments Protocol (MPP).","headers":{"WWW-Authenticate":{"required":true,"description":"MPP Payment challenge. Retry with the corresponding Authorization: Payment credential.","schema":{"type":"string","pattern":"^Payment "}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"410":{"$ref":"#/components/responses/Gone"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/inboxes/{inboxId}/messages":{"get":{"tags":["Messages"],"operationId":"listMessages","security":[{"mailboxToken":[]}],"parameters":[{"$ref":"#/components/parameters/InboxId"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"before","in":"query","description":"ISO timestamp from nextCursor.","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Newest messages first. Outbound status includes final Email Service delivery state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListMessagesResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"410":{"$ref":"#/components/responses/Gone"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/inboxes/{inboxId}/messages/{messageId}":{"get":{"tags":["Messages"],"operationId":"getMessage","security":[{"mailboxToken":[]}],"parameters":[{"$ref":"#/components/parameters/InboxId"},{"$ref":"#/components/parameters/MessageId"}],"responses":{"200":{"description":"Message metadata, text, HTML, raw-message URL, and attachment download URLs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"410":{"$ref":"#/components/responses/Gone"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/inboxes/{inboxId}/messages/{messageId}/raw":{"get":{"tags":["Messages"],"operationId":"getRawMessage","security":[{"mailboxToken":[]}],"parameters":[{"$ref":"#/components/parameters/InboxId"},{"$ref":"#/components/parameters/MessageId"}],"responses":{"200":{"description":"Original RFC 822 message.","content":{"message/rfc822":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"410":{"$ref":"#/components/responses/Gone"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/inboxes/{inboxId}/messages/{messageId}/attachments/{attachmentIndex}":{"get":{"tags":["Messages"],"operationId":"downloadAttachment","security":[{"mailboxToken":[]}],"parameters":[{"$ref":"#/components/parameters/InboxId"},{"$ref":"#/components/parameters/MessageId"},{"name":"attachmentIndex","in":"path","required":true,"schema":{"type":"integer","minimum":0}}],"responses":{"200":{"description":"Attachment bytes. The response Content-Type and filename match the stored attachment.","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"410":{"$ref":"#/components/responses/Gone"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/inboxes/{inboxId}/messages/{messageId}/reply":{"post":{"tags":["Messages"],"operationId":"replyToMessage","security":[{"mailboxToken":[]}],"summary":"Reply to an inbound sender; included with the paid inbox","parameters":[{"$ref":"#/components/parameters/InboxId"},{"$ref":"#/components/parameters/MessageId"},{"$ref":"#/components/parameters/ReplyIdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":20000}},"required":["text"],"additionalProperties":false}}}},"responses":{"202":{"description":"Included reply queued. Poll the message resource for delivered or a terminal failure state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReplyQueuedResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"410":{"$ref":"#/components/responses/Gone"},"422":{"$ref":"#/components/responses/Unprocessable"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/TemporarilyUnavailable"}}}}},"components":{"securitySchemes":{"mailboxToken":{"type":"http","scheme":"bearer","bearerFormat":"MachineInboxToken","description":"Use the mi_live_... token returned by inbox creation. The HTTP client adds the Authorization: Bearer prefix."}},"parameters":{"InboxId":{"name":"inboxId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"MessageId":{"name":"messageId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"description":"Strongly recommended for inbox creation and required for replies. Reuse it only to retry the identical operation.","schema":{"type":"string","minLength":16,"maxLength":200},"example":"agent-task-018e90f3c48a"},"MailboxTokenHeader":{"name":"X-Mailbox-Token","in":"header","required":true,"description":"The mi_live_... mailbox token. Used instead of Authorization: Bearer because the paid retry carries the MPP Payment credential in Authorization.","schema":{"type":"string","pattern":"^mi_live_[A-Za-z0-9_-]+$"}},"ReplyIdempotencyKey":{"name":"Idempotency-Key","in":"header","required":true,"description":"Use a new key for this reply and reuse it only to retry the identical reply.","schema":{"type":"string","minLength":16,"maxLength":200},"example":"agent-reply-018e90f3c48a"}},"responses":{"BadRequest":{"description":"The request is malformed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"A valid mailbox bearer token is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"The inbox is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"The inbox, message, attachment, or route was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Conflict":{"description":"The idempotency key was already used for another operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Gone":{"description":"The inbox has expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unprocessable":{"description":"The inbound sender cannot receive replies.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"RateLimited":{"description":"A request or reply limit was reached.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds before retrying when present."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"TemporarilyUnavailable":{"description":"This operation is temporarily disabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"schemas":{"ErrorResponse":{"type":"object","additionalProperties":false,"properties":{"error":{"type":"object","additionalProperties":false,"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}},"required":["code","message"]}},"required":["error"]},"Mailbox":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"address":{"type":"string","format":"email"},"status":{"type":"string","enum":["pending_payment","active","deleted","expired","suspended","payment_failed"]},"product":{"type":"string","enum":["seven_day_inbox","pro_inbox"]},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"limits":{"type":"object","additionalProperties":false,"properties":{"messages":{"type":"integer","minimum":1},"storageBytes":{"type":"integer","minimum":1}},"required":["messages","storageBytes"]},"usage":{"type":"object","additionalProperties":false,"properties":{"messages":{"type":"integer","minimum":0},"storageBytes":{"type":"integer","minimum":0}},"required":["messages","storageBytes"]}},"required":["id","address","status","product","createdAt","expiresAt","limits","usage"]},"ExtendInboxResponse":{"type":"object","additionalProperties":false,"properties":{"extension":{"type":"object","additionalProperties":false,"properties":{"inboxId":{"type":"string","format":"uuid"},"days":{"type":"integer","minimum":1},"expiresAt":{"type":"string","format":"date-time"}},"required":["inboxId","days","expiresAt"]},"applied":{"const":true},"replayed":{"type":"boolean"}},"required":["extension","applied","replayed"]},"CreateInboxResponse":{"type":"object","additionalProperties":false,"properties":{"inbox":{"$ref":"#/components/schemas/Mailbox"},"token":{"type":"string","pattern":"^mi_live_[A-Za-z0-9_-]+$","description":"Returned only on creation or an idempotent replay."},"tokenNotice":{"type":"string"},"replayed":{"type":"boolean"}},"required":["inbox","token","tokenNotice","replayed"]},"MailboxResponse":{"type":"object","additionalProperties":false,"properties":{"inbox":{"$ref":"#/components/schemas/Mailbox"}},"required":["inbox"]},"DeleteInboxResponse":{"type":"object","additionalProperties":false,"properties":{"deleted":{"const":true},"inboxId":{"type":"string","format":"uuid"}},"required":["deleted","inboxId"]},"Address":{"type":"object","additionalProperties":false,"properties":{"address":{"type":"string","format":"email"},"name":{"type":"string"}},"required":["address"]},"MessageSummary":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"direction":{"type":"string","enum":["inbound","outbound"]},"from":{"$ref":"#/components/schemas/Address"},"to":{"$ref":"#/components/schemas/Address"},"subject":{"type":"string"},"preview":{"type":"string"},"hasAttachments":{"type":"boolean"},"replyable":{"type":"boolean"},"sizeBytes":{"type":"integer","minimum":0},"status":{"type":"string","enum":["pending_payment","received","queued","sending","sent","delivered","deferred","bounced","failed","rejected","complained"]},"receivedAt":{"type":["string","null"],"format":"date-time"},"sentAt":{"type":["string","null"],"format":"date-time"},"deliveredAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","direction","from","to","subject","preview","hasAttachments","replyable","sizeBytes","status","receivedAt","sentAt","deliveredAt","createdAt"]},"ListMessagesResponse":{"type":"object","additionalProperties":false,"properties":{"messages":{"type":"array","items":{"$ref":"#/components/schemas/MessageSummary"}},"nextCursor":{"type":["string","null"],"format":"date-time"}},"required":["messages","nextCursor"]},"Attachment":{"type":"object","additionalProperties":false,"properties":{"index":{"type":"integer","minimum":0},"filename":{"type":"string"},"mimeType":{"type":"string"},"disposition":{"type":["string","null"],"enum":["attachment","inline",null]},"contentId":{"type":"string"},"size":{"type":"integer","minimum":0},"downloadUrl":{"type":"string","format":"uri"}},"required":["index","filename","mimeType","disposition","size","downloadUrl"]},"MessageBody":{"type":"object","additionalProperties":false,"properties":{"text":{"type":["string","null"]},"html":{"type":["string","null"]},"attachments":{"type":"array","items":{"$ref":"#/components/schemas/Attachment"}}},"required":["text","html","attachments"]},"MessageDetail":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"direction":{"type":"string","enum":["inbound","outbound"]},"from":{"$ref":"#/components/schemas/Address"},"to":{"$ref":"#/components/schemas/Address"},"subject":{"type":"string"},"preview":{"type":"string"},"hasAttachments":{"type":"boolean"},"replyable":{"type":"boolean"},"sizeBytes":{"type":"integer","minimum":0},"status":{"type":"string","enum":["pending_payment","received","queued","sending","sent","delivered","deferred","bounced","failed","rejected","complained"]},"receivedAt":{"type":["string","null"],"format":"date-time"},"sentAt":{"type":["string","null"],"format":"date-time"},"deliveredAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"rawUrl":{"type":["string","null"],"format":"uri"},"body":{"anyOf":[{"$ref":"#/components/schemas/MessageBody"},{"type":"null"}]}},"required":["id","direction","from","to","subject","preview","hasAttachments","replyable","sizeBytes","status","receivedAt","sentAt","deliveredAt","createdAt","rawUrl","body"]},"MessageResponse":{"type":"object","additionalProperties":false,"properties":{"message":{"$ref":"#/components/schemas/MessageDetail"}},"required":["message"]},"ReplyQueuedResponse":{"type":"object","additionalProperties":false,"properties":{"reply":{"type":"object","additionalProperties":false,"properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["queued"]},"to":{"type":"string","format":"email"},"subject":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","status","to","subject","createdAt"]},"replayed":{"type":"boolean"}},"required":["reply","replayed"]}}}}