{"openapi":"3.1.0","info":{"title":"MX Forwarder API","version":"0.12.3","description":"Inbound email-to-webhook service. Receive emails and get them delivered as structured JSON to your app. Full markdown docs: https://mx-forwarder.com/docs/api.md","contact":{"email":"hello@mx-forwarder.com"}},"servers":[{"url":"https://mx-forwarder.com","description":"Production"}],"security":[{"bearerAuth":[]}],"paths":{"/api/addresses":{"get":{"tags":["Addresses"],"summary":"List addresses","description":"Returns all forwarding addresses for the authenticated user.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"addresses":{"type":"array","items":{"$ref":"#/components/schemas/Address"}}}}}}}}},"post":{"tags":["Addresses"],"summary":"Create address","description":"Creates a new forwarding address. Emails sent to {local_part}@mail.mx-forwarder.com will be forwarded to the webhook URL.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"local_part":{"type":"string","description":"Local part of the email. Random if omitted."},"webhook_url":{"type":"string","description":"URL to forward emails to"},"webhook_format":{"type":"string","enum":["json","raw"],"default":"json"},"webhook_method":{"type":"string","enum":["POST","GET","PUT","PATCH"],"default":"POST"},"attachment_mode":{"type":"string","enum":["url","inline"],"default":"url","description":"'url' for signed R2 links, 'inline' for base64"},"simulation":{"type":"boolean","default":false,"description":"Test mode — no actual forwarding"},"store_attachments":{"type":"boolean","default":true},"store_content":{"type":"boolean","default":true,"description":"Retain email body/raw after webhook delivery"}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"object","properties":{"id":{"type":"string"},"local_part":{"type":"string"},"email":{"type":"string"}}},"webhook_secret":{"type":"string","description":"Shown only once"}}}}}}}}},"/api/addresses/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["Addresses"],"summary":"Get address","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"address":{"$ref":"#/components/schemas/Address"}}}}}}}},"put":{"tags":["Addresses"],"summary":"Update address","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"webhook_url":{"type":"string"},"webhook_format":{"type":"string","enum":["json","raw"]},"webhook_method":{"type":"string","enum":["POST","GET","PUT","PATCH"]},"attachment_mode":{"type":"string","enum":["url","inline"]},"simulation":{"type":"boolean"},"store_attachments":{"type":"boolean"},"store_content":{"type":"boolean","description":"Retain email body/raw after webhook delivery"},"is_active":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}}}},"delete":{"tags":["Addresses"],"summary":"Delete address","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}}}}},"/api/emails":{"get":{"tags":["Emails"],"summary":"List emails","parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"Full-text search"},{"name":"address_id","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":100}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"emails":{"type":"array","items":{"$ref":"#/components/schemas/Email"}},"next_cursor":{"type":"string","nullable":true}}}}}}}}},"/api/emails/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["Emails"],"summary":"Get email details","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"email":{"$ref":"#/components/schemas/Email"},"attachments":{"type":"array","items":{"$ref":"#/components/schemas/Attachment"}},"deliveries":{"type":"array","items":{"$ref":"#/components/schemas/Delivery"}}}}}}}}}},"/api/emails/{id}/raw":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["Emails"],"summary":"Download raw email","responses":{"200":{"description":"RFC822 .eml file","content":{"message/rfc822":{"schema":{"type":"string","format":"binary"}}}}}}},"/api/emails/{id}/retry":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"tags":["Emails"],"summary":"Retry delivery","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}}}}},"/api/deliveries":{"get":{"tags":["Deliveries"],"summary":"List deliveries","parameters":[{"name":"address_id","in":"query","schema":{"type":"string"}},{"name":"email_id","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string","enum":["pending","delivered","failed"]}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":100}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"deliveries":{"type":"array","items":{"$ref":"#/components/schemas/Delivery"}},"next_cursor":{"type":"string","nullable":true}}}}}}}}},"/api/usage":{"get":{"tags":["Usage"],"summary":"Get usage stats","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Usage"}}}}}}},"/api/reseller/sub-accounts":{"get":{"tags":["Reseller"],"summary":"List sub-accounts","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"sub_accounts":{"type":"array","items":{"$ref":"#/components/schemas/SubAccount"}},"total":{"type":"integer"}}}}}}}},"post":{"tags":["Reseller"],"summary":"Create sub-account","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","description":"Identifier for the sub-account (can be synthetic)"},"plan":{"type":"string","default":"free","description":"Plan for address/retention limits"},"external_id":{"type":"string","description":"Your own customer ID for mapping"}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"sub_account":{"$ref":"#/components/schemas/SubAccount"},"api_key":{"type":"string","description":"Shown only once"}}}}}}}}},"/api/reseller/sub-accounts/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"patch":{"tags":["Reseller"],"summary":"Update sub-account","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"plan":{"type":"string"},"external_id":{"type":"string","description":"Your customer reference"}}}}}},"responses":{"200":{"description":"Success"}}},"delete":{"tags":["Reseller"],"summary":"Delete sub-account","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"boolean"}}}}}}}}},"/api/reseller/sub-accounts/{id}/usage":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"tags":["Reseller"],"summary":"Sub-account usage","description":"Get monthly usage breakdown for a specific sub-account with optional date range.","parameters":[{"name":"from","in":"query","schema":{"type":"string"},"description":"Start month (YYYY-MM)"},{"name":"to","in":"query","schema":{"type":"string"},"description":"End month (YYYY-MM)"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubAccountUsage"}}}}}}},"/api/reseller/settings":{"put":{"tags":["Reseller"],"summary":"Update reseller settings","description":"Update org-level defaults. store_content_default controls whether new sub-account addresses retain email content after delivery.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"store_content_default":{"type":"boolean","description":"Default content retention for new sub-account addresses"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}}}}}}}},"/api/reseller/usage":{"get":{"tags":["Reseller"],"summary":"Aggregate usage","parameters":[{"name":"month","in":"query","schema":{"type":"string"},"description":"YYYY-MM (default: current)"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResellerUsage"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key prefixed with mf_live_"}},"schemas":{"Address":{"type":"object","properties":{"id":{"type":"string"},"local_part":{"type":"string"},"webhook_url":{"type":"string"},"webhook_format":{"type":"string"},"webhook_method":{"type":"string"},"attachment_mode":{"type":"string"},"is_active":{"type":"integer"},"simulation":{"type":"integer"},"store_attachments":{"type":"integer"},"store_content":{"type":"integer","description":"Whether email body/raw is retained after webhook delivery"},"created_at":{"type":"string"},"updated_at":{"type":"string"}}},"Email":{"type":"object","properties":{"id":{"type":"string"},"address_id":{"type":"string"},"message_id":{"type":"string"},"envelope_from":{"type":"string"},"envelope_to":{"type":"string"},"from_addr":{"type":"string"},"to_addr":{"type":"string"},"subject":{"type":"string"},"text_body":{"type":"string"},"html_body":{"type":"string"},"headers_json":{"type":"string"},"size_bytes":{"type":"integer"},"spf_result":{"type":"string"},"dkim_result":{"type":"string"},"dmarc_result":{"type":"string"},"received_at":{"type":"string"}}},"Attachment":{"type":"object","properties":{"id":{"type":"string"},"email_id":{"type":"string"},"file_name":{"type":"string"},"content_type":{"type":"string"},"size_bytes":{"type":"integer"}}},"Delivery":{"type":"object","properties":{"id":{"type":"string"},"email_id":{"type":"string"},"address_id":{"type":"string"},"status":{"type":"string","enum":["pending","delivered","failed"]},"http_status":{"type":"integer","nullable":true},"response_body":{"type":"string","nullable":true},"attempt_count":{"type":"integer"},"error_message":{"type":"string","nullable":true},"last_attempted_at":{"type":"string","nullable":true}}},"Usage":{"type":"object","properties":{"plan":{"type":"string"},"month":{"type":"string"},"email_count":{"type":"integer"},"email_limit":{"type":"integer"},"attachment_bytes":{"type":"integer"},"attachment_limit":{"type":"integer"},"addresses_used":{"type":"integer"},"addresses_limit":{"type":"integer"}}},"SubAccount":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string","description":"Identifier (can be synthetic)"},"plan":{"type":"string"},"external_id":{"type":"string","nullable":true,"description":"Your customer reference"},"clerk_id":{"type":"string"},"created_at":{"type":"string"}}},"SubAccountUsage":{"type":"object","properties":{"sub_account":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"}}},"months":{"type":"array","items":{"type":"object","properties":{"month":{"type":"string"},"email_count":{"type":"integer"},"attachment_bytes":{"type":"integer"}}}},"total":{"type":"object","properties":{"email_count":{"type":"integer"},"attachment_bytes":{"type":"integer"}}}}},"ResellerUsage":{"type":"object","properties":{"month":{"type":"string"},"aggregate":{"type":"object","properties":{"email_count":{"type":"integer"},"attachment_bytes":{"type":"integer"}}},"limits":{"type":"object","properties":{"emails_per_month":{"type":"integer"},"attachment_storage_bytes":{"type":"integer"}}},"sub_accounts":{"type":"array","items":{"type":"object","properties":{"user_id":{"type":"string"},"email":{"type":"string"},"email_count":{"type":"integer"},"attachment_bytes":{"type":"integer"}}}}}}}}}