{"openapi":"3.1.0","info":{"title":"BoomSauce API","version":"1.0","description":"Programmatic email sending, reply management, contact CRUD, webhook subscriptions, and warmup control. Authenticate with a bs_live_... or bs_test_... Bearer token. See /api-docs for narrative docs + curl examples.","contact":{"name":"BoomSauce","url":"https://app.boomsauce.com/support"}},"servers":[{"url":"https://app.boomsauce.com/api/v1"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"bs_live_... / bs_test_..."}},"parameters":{"Cursor":{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque cursor from a prior next_cursor response."},"Limit":{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},"Since":{"name":"since","in":"query","schema":{"type":"string","format":"date-time"}},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","schema":{"type":"string"},"description":"Deduplicate retries for 24h. Repeat calls return the cached response."}},"schemas":{"Recipient":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"mailbox_id":{"type":"integer","nullable":true}}},"SendResult":{"type":"object","required":["send_id","status","mode"],"properties":{"send_id":{"type":"integer"},"status":{"type":"string","enum":["sent","queued","test"]},"mailbox_id":{"type":"integer","nullable":true},"message_id":{"type":"string","nullable":true},"mode":{"type":"string","enum":["live","test"]}}},"Send":{"type":"object","properties":{"id":{"type":"integer"},"status":{"type":"string"},"from_brand_id":{"type":"integer"},"mailbox_id":{"type":"integer","nullable":true},"message_id":{"type":"string","nullable":true},"to":{"type":"object","properties":{"email":{"type":"string"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true}}},"subject":{"type":"string","nullable":true},"bounce_reason":{"type":"string","nullable":true},"timestamps":{"type":"object","properties":{"sent_at":{"type":"string","format":"date-time","nullable":true},"opened_at":{"type":"string","format":"date-time","nullable":true},"clicked_at":{"type":"string","format":"date-time","nullable":true},"bounced_at":{"type":"string","format":"date-time","nullable":true},"replied_at":{"type":"string","format":"date-time","nullable":true},"unsubscribed_at":{"type":"string","format":"date-time","nullable":true}}}}},"Reply":{"type":"object","properties":{"id":{"type":"integer"},"from_email":{"type":"string"},"subject":{"type":"string","nullable":true},"body":{"type":"string","nullable":true},"classification":{"type":"string","nullable":true},"confidence":{"type":"number","nullable":true},"received_at":{"type":"string","format":"date-time"},"is_warmup":{"type":"boolean"},"send_id":{"type":"integer","nullable":true},"contact":{"type":"object","nullable":true,"properties":{"id":{"type":"integer"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"status":{"type":"string"}}},"campaign_id":{"type":"integer","nullable":true},"sequence_id":{"type":"integer","nullable":true}}},"Contact":{"type":"object","properties":{"id":{"type":"integer"},"email":{"type":"string"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"linkedin_url":{"type":"string","nullable":true},"location":{"type":"string","nullable":true},"company_website":{"type":"string","nullable":true},"industry":{"type":"string","nullable":true},"status":{"type":"string"},"tags":{"type":"array","items":{"type":"string"},"nullable":true},"metadata":{"type":"object"},"engagement_score":{"type":"number","nullable":true},"last_engagement_at":{"type":"string","format":"date-time","nullable":true},"total_sends":{"type":"integer"},"total_opens":{"type":"integer"},"total_clicks":{"type":"integer"},"total_replies":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Webhook":{"type":"object","properties":{"id":{"type":"integer"},"url":{"type":"string"},"label":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"secret_prefix":{"type":"string"},"created_by_email":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"last_delivery_at":{"type":"string","format":"date-time","nullable":true},"last_failure_at":{"type":"string","format":"date-time","nullable":true},"last_failure_reason":{"type":"string","nullable":true},"consecutive_failures":{"type":"integer"},"paused_at":{"type":"string","format":"date-time","nullable":true},"revoked_at":{"type":"string","format":"date-time","nullable":true}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/wallet":{"get":{"summary":"Wallet balance","operationId":"getWallet","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"balance_cents":{"type":"integer"},"balance_usd":{"type":"number"},"client_id":{"type":"integer"},"mode":{"type":"string"}}}}}}}}},"/meter/rates":{"get":{"summary":"Live rate card","operationId":"getMeterRates","description":"Returns the canonical rate card — every meter, its price, its billing unit, and the ledger account code it posts to. Treat this as authoritative; it mirrors the billing engine.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","example":"rate_card"},"meters":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"},"description":{"type":"string"},"retail_cents":{"type":"integer"},"unit":{"type":"string"},"display_unit":{"type":"string"},"display_rate":{"type":"string"},"block_size":{"type":"integer","nullable":true},"ledger_revenue_code":{"type":"string"}}}}}}}}}}}},"/meter/consumption":{"get":{"summary":"Per-meter consumption","operationId":"getMeterConsumption","description":"Returns consumption per meter for a window. Defaults to month-to-date.","parameters":[{"name":"period","in":"query","schema":{"type":"string","enum":["mtd","7d","30d"],"default":"mtd"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","example":"meter_consumption"},"period":{"type":"string"},"period_start":{"type":"string","format":"date-time"},"period_end":{"type":"string","format":"date-time"},"meters":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"units":{"type":"integer","nullable":true},"unit_label":{"type":"string"},"cents":{"type":"integer"}}}},"total_cents":{"type":"integer"}}}}}}}}},"/meter/forecast":{"get":{"summary":"Wallet burn rate + runway","operationId":"getMeterForecast","description":"Returns average daily burn, projected monthly spend, and estimated wallet runway. Useful for spend-cap automation.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","example":"meter_forecast"},"as_of":{"type":"string","format":"date-time"},"wallet_balance_cents":{"type":"integer"},"month_to_date_cents":{"type":"integer"},"avg_daily_burn_cents":{"type":"integer"},"projected_monthly_cents":{"type":"integer"},"days_wallet_lasts":{"type":"integer","nullable":true},"runway_end_iso":{"type":"string","format":"date-time","nullable":true}}}}}}}}},"/sends":{"get":{"summary":"List sends","operationId":"listSends","parameters":[{"$ref":"#/components/parameters/Since"},{"name":"status","in":"query","schema":{"type":"string"}},{"name":"brand_id","in":"query","schema":{"type":"integer"}},{"name":"contact_email","in":"query","schema":{"type":"string"}},{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Send"}},"next_cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}},"post":{"summary":"Send one email","operationId":"createSend","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["from_brand_id","to","subject","html"],"properties":{"from_brand_id":{"type":"integer"},"to":{"$ref":"#/components/schemas/Recipient"},"subject":{"type":"string"},"html":{"type":"string"},"text":{"type":"string"},"spintax":{"type":"boolean"},"mailbox_rotation":{"type":"boolean"},"mailbox_id":{"type":"integer","nullable":true}}}}}},"responses":{"201":{"description":"Sent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendResult"}}}},"400":{"description":"Bad input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit or mailbox cap","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/sends/batch":{"post":{"summary":"Send a batch of up to 500","operationId":"createBatchSend","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["from_brand_id","subject","html","recipients"],"properties":{"from_brand_id":{"type":"integer"},"subject":{"type":"string"},"html":{"type":"string"},"text":{"type":"string"},"spintax":{"type":"boolean"},"mailbox_rotation":{"type":"boolean"},"recipients":{"type":"array","maxItems":500,"items":{"$ref":"#/components/schemas/Recipient"}}}}}}},"responses":{"202":{"description":"Accepted for async delivery","content":{"application/json":{"schema":{"type":"object","properties":{"batch_id":{"type":"string","format":"uuid"},"accepted":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"send_id":{"type":"integer"},"email":{"type":"string"}}}},"rejected":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"email":{"type":"string","nullable":true},"error":{"type":"string"}}}},"counts":{"type":"object","properties":{"accepted":{"type":"integer"},"rejected":{"type":"integer"},"total":{"type":"integer"}}},"mode":{"type":"string"},"queued":{"type":"boolean"}}}}}}}}},"/sends/{id}":{"get":{"summary":"Get send status","operationId":"getSend","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Send"}}}},"404":{"description":"Not found"}}}},"/replies":{"get":{"summary":"List inbound replies","operationId":"listReplies","parameters":[{"$ref":"#/components/parameters/Since"},{"name":"classification","in":"query","schema":{"type":"string","enum":["interested","not_interested","question","ooo","bounce","unsubscribe","auto_reply","other"]}},{"name":"include_warmup","in":"query","schema":{"type":"boolean","default":false}},{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Reply"}},"next_cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}},"post":{"summary":"Reply on a thread","operationId":"createReply","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"in_reply_to_send_id":{"type":"integer"},"in_reply_to_reply_id":{"type":"integer"},"html":{"type":"string"},"text":{"type":"string"},"subject":{"type":"string"},"spintax":{"type":"boolean"},"merge_vars":{"type":"object"}}}}}},"responses":{"201":{"description":"Sent"}}}},"/contacts":{"get":{"summary":"List contacts","operationId":"listContacts","parameters":[{"name":"search","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string"}},{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Contact"}},"next_cursor":{"type":"string","nullable":true},"has_more":{"type":"boolean"}}}}}}}},"post":{"summary":"Create or upsert a contact","operationId":"upsertContact","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"},"first_name":{"type":"string"},"last_name":{"type":"string"},"title":{"type":"string"},"company":{"type":"string"},"phone":{"type":"string"},"linkedin_url":{"type":"string"},"location":{"type":"string"},"company_website":{"type":"string"},"industry":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object"}}}}}},"responses":{"200":{"description":"Upserted","content":{"application/json":{"schema":{"type":"object","properties":{"contact":{"$ref":"#/components/schemas/Contact"},"created":{"type":"boolean"}}}}}}}}},"/contacts/{id}":{"get":{"summary":"Get contact by id or email","operationId":"getContact","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}},"patch":{"summary":"Partial update","operationId":"updateContact","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK"}}},"delete":{"summary":"Soft delete","operationId":"deleteContact","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK"}}}},"/webhooks":{"get":{"summary":"List webhook subscriptions","operationId":"listWebhooks","responses":{"200":{"description":"OK"}}},"post":{"summary":"Create webhook subscription","operationId":"createWebhook","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","events"],"properties":{"url":{"type":"string","format":"uri"},"label":{"type":"string"},"events":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"201":{"description":"Created; signing secret returned ONCE"}}}},"/webhooks/{id}":{"get":{"summary":"Get webhook","operationId":"getWebhook","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK"}}},"patch":{"summary":"Update events list / label / pause","operationId":"updateWebhook","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK"}}},"delete":{"summary":"Revoke","operationId":"revokeWebhook","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK"}}}},"/webhooks/{id}/deliveries":{"get":{"summary":"Delivery log","operationId":"listWebhookDeliveries","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}},{"$ref":"#/components/parameters/Cursor"},{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"description":"OK"}}}},"/webhooks/{id}/test":{"post":{"summary":"Send a test delivery","operationId":"testWebhook","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"202":{"description":"Enqueued"}}}},"/warmup":{"get":{"summary":"List warmup status across mailboxes","operationId":"listWarmup","responses":{"200":{"description":"OK"}}},"post":{"summary":"Enable warmup on a mailbox","operationId":"enableWarmup","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["mailbox_id"],"properties":{"mailbox_id":{"type":"integer"},"daily_volume":{"type":"integer","minimum":5,"maximum":1000,"default":25},"duration_days":{"type":"integer","default":30}}}}}},"responses":{"201":{"description":"Enabled"}}}},"/warmup/{mailbox_id}":{"get":{"summary":"Warmup status for one mailbox","operationId":"getWarmup","parameters":[{"name":"mailbox_id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK"}}},"patch":{"summary":"Change volume or status","operationId":"updateWarmup","parameters":[{"name":"mailbox_id","in":"path","required":true,"schema":{"type":"integer"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["active","paused","cancelled"]},"daily_volume":{"type":"integer","minimum":5,"maximum":1000}}}}}},"responses":{"200":{"description":"OK"}}},"delete":{"summary":"Cancel warmup","operationId":"cancelWarmup","parameters":[{"name":"mailbox_id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK"}}}}}}