{"openapi":"3.0.3","info":{"title":"NoxMail API","version":"1.0.0","description":"Working API reference for creating temporary inboxes, validating inbox ownership, reading received messages, and importing inbound messages from a trusted worker."},"servers":[{"url":"https:\/\/noxmail.app"}],"tags":[{"name":"Inbox","description":"Public temporary inbox operations."},{"name":"Messages","description":"Read messages for an existing inbox UUID."},{"name":"Inbound worker","description":"Server-to-server endpoint used by Cloudflare Email Worker or another trusted mail importer."},{"name":"Docs","description":"Documentation metadata."}],"paths":{"\/api\/email-box":{"post":{"tags":["Inbox"],"summary":"Create a new temporary inbox","description":"Creates and returns a temporary email address. When Gmail dot-trick mode is enabled, the generated address is a Gmail alias; otherwise it uses an active NoxMail domain.","responses":{"200":{"description":"Temporary inbox created.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/TemporaryEmailBox"},"example":{"email":"arthur11.6091@noxmail.app","uuid":"80d47aee-0585-4e88-acc2-b8bbf7c738b2"}}}},"404":{"$ref":"#\/components\/responses\/NoDomains"}}}},"\/api\/email-box\/validate":{"post":{"tags":["Inbox"],"summary":"Validate an inbox email and UUID pair","requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ValidateEmailBoxRequest"},"example":{"email":"arthur11.6091@noxmail.app","uuid":"80d47aee-0585-4e88-acc2-b8bbf7c738b2"}}}},"responses":{"200":{"description":"Validation result.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ValidateEmailBoxResponse"},"example":{"is_valid":true}}}},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}},"\/api\/email-box\/{emailBoxUuid}\/emails":{"get":{"tags":["Messages"],"summary":"List messages in an inbox","description":"Returns all received messages for the temporary inbox UUID and updates the inbox last-accessed timestamp.","parameters":[{"$ref":"#\/components\/parameters\/EmailBoxUuid"}],"responses":{"200":{"description":"Message summary list.","content":{"application\/json":{"schema":{"type":"array","items":{"$ref":"#\/components\/schemas\/ReceivedEmailSummary"}},"example":[]}}},"404":{"$ref":"#\/components\/responses\/NotFound"}}}},"\/api\/email-box\/{emailBoxUuid}\/email\/{emailUuid}":{"get":{"tags":["Messages"],"summary":"Get one message as JSON","description":"Returns one received email including its HTML body and marks it as read.","parameters":[{"$ref":"#\/components\/parameters\/EmailBoxUuid"},{"$ref":"#\/components\/parameters\/EmailUuid"}],"responses":{"200":{"description":"Message detail.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/ReceivedEmailDetail"}}}},"404":{"$ref":"#\/components\/responses\/NotFound"}}}},"\/email-box\/{emailBoxUuid}\/email\/{emailUuid}":{"get":{"tags":["Messages"],"summary":"View one message as HTML","description":"Browser-friendly HTML view for a received email.","parameters":[{"$ref":"#\/components\/parameters\/EmailBoxUuid"},{"$ref":"#\/components\/parameters\/EmailUuid"}],"responses":{"200":{"description":"Rendered email HTML page.","content":{"text\/html":{"schema":{"type":"string"}}}},"404":{"$ref":"#\/components\/responses\/NotFound"}}}},"\/api\/email":{"post":{"tags":["Inbound worker"],"summary":"Import an inbound email","description":"Authenticated server-to-server endpoint. A Cloudflare Email Worker, Gmail dot-trick sync process, or another trusted importer posts parsed messages here. The Authorization header must match CREATE_RECEIVED_EMAIL_API_AUTHORIZATION_KEY.","security":[{"workerBearer":[]}],"requestBody":{"required":true,"content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/CreateEmailRequest"},"example":{"real_from":"sender@example.com","real_to":"arthur11.6091@noxmail.app","subject":"Hello from API","from_name":"Example Sender","from_address":"sender@example.com","to_multiple":["arthur11.6091@noxmail.app"],"bcc_multiple":[],"html":"\u003Cp\u003EHello NoxMail\u003C\/p\u003E","metadata":{"source":"worker"}}}}},"responses":{"201":{"description":"Message accepted.","content":{"application\/json":{"schema":{"type":"string"},"example":"OK"}}},"401":{"$ref":"#\/components\/responses\/UnauthorizedWorker"},"422":{"$ref":"#\/components\/responses\/ValidationError"}}}},"\/api-docs\/openapi.json":{"get":{"tags":["Docs"],"summary":"Download this OpenAPI document","responses":{"200":{"description":"OpenAPI JSON document.","content":{"application\/json":{"schema":{"type":"object"}}}}}}}},"components":{"securitySchemes":{"workerBearer":{"type":"http","scheme":"bearer","description":"Use the CREATE_RECEIVED_EMAIL_API_AUTHORIZATION_KEY value as the bearer token."}},"parameters":{"EmailBoxUuid":{"name":"emailBoxUuid","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"example":"80d47aee-0585-4e88-acc2-b8bbf7c738b2"},"EmailUuid":{"name":"emailUuid","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}},"schemas":{"TemporaryEmailBox":{"type":"object","required":["email","uuid"],"properties":{"email":{"type":"string","format":"email"},"uuid":{"type":"string","format":"uuid"}}},"ValidateEmailBoxRequest":{"type":"object","required":["email","uuid"],"properties":{"email":{"type":"string","format":"email"},"uuid":{"type":"string","format":"uuid"}}},"ValidateEmailBoxResponse":{"type":"object","required":["is_valid"],"properties":{"is_valid":{"type":"boolean"}}},"ReceivedEmailSummary":{"type":"object","required":["uuid","from","real_to","subject","received_at"],"properties":{"uuid":{"type":"string","format":"uuid"},"from":{"type":"string"},"real_to":{"type":"string","format":"email"},"from_name":{"type":"string","nullable":true},"subject":{"type":"string"},"received_at":{"type":"string","format":"date-time"}}},"ReceivedEmailDetail":{"allOf":[{"$ref":"#\/components\/schemas\/ReceivedEmailSummary"},{"type":"object","properties":{"html":{"type":"string","nullable":true}}}]},"CreateEmailRequest":{"type":"object","required":["real_from","real_to"],"properties":{"real_from":{"type":"string","format":"email"},"real_to":{"type":"string","format":"email"},"subject":{"type":"string","nullable":true},"from_name":{"type":"string","nullable":true},"from_address":{"type":"string","format":"email","nullable":true},"to_multiple":{"type":"array","items":{"type":"string","format":"email"},"nullable":true},"bcc_multiple":{"type":"array","items":{"type":"string","format":"email"},"nullable":true},"html":{"type":"string","nullable":true},"metadata":{"type":"object","additionalProperties":true,"nullable":true}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"integer"}}}},"responses":{"NoDomains":{"description":"No active domains are configured.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"},"example":{"error":"There are no assigned domains","code":1001}}}},"UnauthorizedWorker":{"description":"Authorization header is missing or invalid.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Error"},"example":{"error":"Bad Authorization header. Verify if Authorization header has correct value.","code":1002}}}},"ValidationError":{"description":"Request JSON does not match the expected shape."},"NotFound":{"description":"The requested inbox or message was not found."}}}}