{"openapi":"3.1.0","info":{"title":"Mailgot API","description":"Extract member names + free-mail addresses from PDF/Excel/CSV lists, filter out corporate domains, validate deliverability, and export.\n\n**Auth:** send `X-API-Key: <key>` on every endpoint except `/api/v1/health`.\n\n**Note on validation:** `valid` means well-formed syntax AND the domain accepts mail (MX record). It does not guarantee an individual mailbox exists — that cannot be confirmed for gmail/yahoo/outlook without sending real email.","version":"1.0.0"},"paths":{"/api/v1/health":{"get":{"tags":["meta"],"summary":"Health","description":"Liveness probe. No authentication required.","operationId":"health_api_v1_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthOut"}}}}}}},"/api/v1/analyze":{"post":{"tags":["documents"],"summary":"Analyze","description":"Inspect a document without processing it.\n\nReturns the detected structure, the suggested column mapping, and a preview\nso an agent can decide whether to accept the mapping or override it when\ncalling `/api/v1/process`.","operationId":"analyze_api_v1_analyze_post","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_analyze_api_v1_analyze_post"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/process":{"post":{"tags":["documents"],"summary":"Process Document","description":"Extract names + emails, keep only free-mail domains, and validate them.\n\nReturns per-row results with `status` ('valid'/'invalid') and a `reason`,\nplus summary counts. Set `include_excluded=true` to audit what was dropped.","operationId":"process_document_api_v1_process_post","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_process_document_api_v1_process_post"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/process/xlsx":{"post":{"tags":["documents"],"summary":"Process Document Xlsx","description":"Same as /process but responds with the .xlsx file (first name, last name, full name, email, status).","operationId":"process_document_xlsx_api_v1_process_xlsx_post","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_process_document_xlsx_api_v1_process_xlsx_post"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/invite-requests":{"post":{"tags":["meta"],"summary":"Request Invite","description":"Request an invite code (public — powers the landing page form).\n\nRecords the request for an admin to approve; it never issues a code directly.","operationId":"request_invite_api_v1_invite_requests_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InviteRequestIn"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/validate-emails":{"post":{"tags":["emails"],"summary":"Validate Emails","description":"Validate a plain list of addresses (syntax + domain MX), no file needed.","operationId":"validate_emails_api_v1_validate_emails_post","parameters":[{"name":"X-API-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Api-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidateIn"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"Body_analyze_api_v1_analyze_post":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File","description":"PDF, XLSX, XLS or CSV member list."},"column_starts":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Column Starts","description":"PDF only: comma-separated column left-edge x-positions to override auto-detection."}},"type":"object","required":["file"],"title":"Body_analyze_api_v1_analyze_post"},"Body_process_document_api_v1_process_post":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File","description":"PDF, XLSX, XLS or CSV member list."},"has_header":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Has Header","description":"Override header detection (auto if omitted)."},"email_column":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email Column","description":"Column name holding the email address."},"name_mode":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name Mode","description":"'full' (one name column) or 'parts' (first+last)."},"full_name_column":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Full Name Column","description":"Column name for the full name."},"first_name_column":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"First Name Column","description":"Column name for the first name."},"last_name_column":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Name Column","description":"Column name for the last name."},"column_starts":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Column Starts","description":"PDF only: column boundary override."},"include_excluded":{"type":"boolean","title":"Include Excluded","description":"Also return rows dropped for non-free domains.","default":false}},"type":"object","required":["file"],"title":"Body_process_document_api_v1_process_post"},"Body_process_document_xlsx_api_v1_process_xlsx_post":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File"},"has_header":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Has Header"},"email_column":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email Column"},"name_mode":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name Mode"},"full_name_column":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Full Name Column"},"first_name_column":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"First Name Column"},"last_name_column":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Name Column"},"column_starts":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Column Starts"}},"type":"object","required":["file"],"title":"Body_process_document_xlsx_api_v1_process_xlsx_post"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"HealthOut":{"properties":{"status":{"type":"string","title":"Status","default":"ok"},"version":{"type":"string","title":"Version"},"free_domains":{"type":"integer","title":"Free Domains"},"max_upload_mb":{"type":"integer","title":"Max Upload Mb"}},"type":"object","required":["version","free_domains","max_upload_mb"],"title":"HealthOut"},"InviteRequestIn":{"properties":{"name":{"type":"string","maxLength":120,"title":"Name","description":"Requester's name.","default":""},"email":{"type":"string","maxLength":200,"title":"Email","description":"Requester's email address."},"note":{"type":"string","maxLength":500,"title":"Note","description":"What they need access for.","default":""}},"type":"object","required":["email"],"title":"InviteRequestIn"},"ValidateIn":{"properties":{"emails":{"items":{"type":"string"},"type":"array","maxItems":5000,"title":"Emails","description":"Addresses to check."},"free_domains_only":{"type":"boolean","title":"Free Domains Only","description":"If true, mark non-free (corporate) domains as excluded.","default":false}},"type":"object","required":["emails"],"title":"ValidateIn"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}}