{"openapi":"3.1.0","info":{"title":"NotifPool API","version":"1.0.0","description":"One API for transactional e-mail and SMS. Prices in EUR, VAT excluded.","contact":{"email":"hello@notifpool.com"}},"servers":[{"url":"https://api.notifpool.com"}],"security":[{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"API key starting with np_live_"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string"},"message":{"type":"string"}}}}},"Message":{"type":"object","properties":{"id":{"type":"string"},"channel":{"type":"string","enum":["email","sms"]},"to":{"type":"array","items":{"type":"string"}},"from":{"type":"string"},"subject":{"type":"string"},"status":{"type":"string","enum":["scheduled","queued","sent","delivered","bounced","complained","failed","cancelled"]},"error":{"type":"string"},"cost":{"type":"number"},"segments":{"type":"integer"},"country":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"cc":{"type":"array","items":{"type":"string"}},"bcc":{"type":"array","items":{"type":"string"}},"attachments":{"type":"array","items":{"type":"object","properties":{"filename":{"type":"string"},"size":{"type":"integer"},"content_type":{"type":"string"}}}},"tags":{"type":"array","items":{"type":"string"}},"template":{"type":"string"},"send_at":{"type":"string","format":"date-time"},"suppressed":{"type":"array","items":{"type":"string"}}}},"EmailInput":{"type":"object","required":["channel","to","subject"],"properties":{"channel":{"const":"email"},"to":{"oneOf":[{"type":"string","format":"email"},{"type":"array","maxItems":50,"items":{"type":"string","format":"email"}}]},"from":{"type":"string"},"reply_to":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"subject":{"type":"string"},"text":{"type":"string"},"html":{"type":"string"},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"cc":{"type":"array","maxItems":50,"items":{"type":"string","format":"email"}},"bcc":{"type":"array","maxItems":50,"items":{"type":"string","format":"email"}},"headers":{"type":"object","additionalProperties":{"type":"string"}},"attachments":{"type":"array","maxItems":10,"items":{"type":"object","required":["filename"],"properties":{"filename":{"type":"string"},"content":{"type":"string","description":"base64"},"url":{"type":"string","format":"uri"},"content_type":{"type":"string"},"inline":{"type":"boolean"},"cid":{"type":"string"}}}},"tags":{"type":"array","maxItems":5,"items":{"type":"string","pattern":"^[a-z0-9_-]{1,40}$"}},"template":{"type":"string"},"variables":{"type":"object"},"send_at":{"type":"string","format":"date-time"}}},"SmsInput":{"type":"object","required":["channel","to","text"],"properties":{"channel":{"const":"sms"},"to":{"oneOf":[{"type":"string"},{"type":"array","maxItems":50,"items":{"type":"string"}}]},"text":{"type":"string","maxLength":918},"from":{"type":"string","pattern":"^[A-Za-z0-9]{3,11}$"},"default_country":{"type":"string","minLength":2,"maxLength":2},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"tags":{"type":"array","maxItems":5,"items":{"type":"string","pattern":"^[a-z0-9_-]{1,40}$"}},"template":{"type":"string"},"variables":{"type":"object"},"send_at":{"type":"string","format":"date-time"}}},"Domain":{"type":"object","properties":{"domain":{"type":"string"},"status":{"type":"string"},"records":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string"},"value":{"type":"string"},"priority":{"type":"integer"},"purpose":{"type":"string"}}}},"mail_from":{"type":"object","properties":{"domain":{"type":"string"},"status":{"type":"string"}}}}},"Account":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"balance":{"type":"number"},"spent":{"type":"number"},"sent_email":{"type":"integer"},"sent_sms":{"type":"integer"},"webhook_url":{"type":["string","null"]},"created_at":{"type":"string"}}},"Template":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"subject":{"type":"string"},"text":{"type":"string"},"html":{"type":"string"},"sms_text":{"type":"string"},"from":{"type":"string"},"reply_to":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"variables":{"type":"array","items":{"type":"string"}},"channels":{"type":"array","items":{"type":"string"}},"created_at":{"type":"string"},"updated_at":{"type":"string"}}}}},"paths":{"/v1/signup":{"post":{"security":[],"summary":"Create an account and receive an API key by e-mail","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","name"],"properties":{"email":{"type":"string","format":"email"},"name":{"type":"string"}}}}}},"responses":{"201":{"description":"Key sent by e-mail"},"429":{"description":"Too many sign-ups","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/prices":{"get":{"security":[],"summary":"Public price list","responses":{"200":{"description":"Prices"}}}},"/v1/messages":{"post":{"summary":"Send an e-mail or an SMS","parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string","maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/EmailInput"},{"$ref":"#/components/schemas/SmsInput"}],"discriminator":{"propertyName":"channel"}}}}},"responses":{"200":{"description":"Replay of an idempotent request"},"202":{"description":"Accepted and handed to the provider","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Message"}}}},"400":{"description":"Invalid request"},"402":{"description":"Insufficient balance"},"403":{"description":"Sender domain not verified"},"429":{"description":"Rate limited"},"502":{"description":"Provider refused; nothing charged"}}},"get":{"summary":"List messages, newest first","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","maximum":200}},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"tag","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string"}},{"name":"channel","in":"query","schema":{"type":"string","enum":["email","sms"]}}],"responses":{"200":{"description":"Page","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Message"}},"next_cursor":{"type":["string","null"]}}}}}}}}},"/v1/messages/{id}":{"get":{"summary":"Read a message","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Message"}}}},"404":{"description":"Not found"}}},"delete":{"summary":"Cancel a scheduled message","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Cancelled"},"400":{"description":"Not scheduled"}}}},"/v1/domains":{"get":{"summary":"List sender domains","responses":{"200":{"description":"Domains"}}},"post":{"summary":"Add a sender domain","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["domain"],"properties":{"domain":{"type":"string"}}}}}},"responses":{"201":{"description":"DNS records to publish","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Domain"}}}}}}},"/v1/domains/{domain}":{"get":{"summary":"Re-check a domain","parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Domain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Domain"}}}}}},"delete":{"summary":"Remove a domain","parameters":[{"name":"domain","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted"}}}},"/v1/account":{"get":{"summary":"Balance and usage","responses":{"200":{"description":"Account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"}}}}}}},"/v1/account/webhook":{"put":{"summary":"Set or remove the status webhook","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":["string","null"],"format":"uri"}}}}}},"responses":{"200":{"description":"Webhook and signing secret"}}}},"/v1/account/keys":{"get":{"summary":"List API keys","responses":{"200":{"description":"Keys"}}},"post":{"summary":"Create an API key","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string"}}}}}},"responses":{"201":{"description":"Key, shown once"}}}},"/v1/account/keys/{id}":{"delete":{"summary":"Revoke an API key","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Revoked"}}}},"/v1/topups":{"get":{"summary":"List top-ups","responses":{"200":{"description":"Top-ups and packs"}}},"post":{"summary":"Buy credit","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount"],"properties":{"amount":{"type":"integer","enum":[10,25,50,100,250,500]}}}}}},"responses":{"201":{"description":"Checkout URL"}}}},"/v1/templates":{"get":{"summary":"List templates","responses":{"200":{"description":"Templates"}}},"post":{"summary":"Create a template","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"subject":{"type":"string"},"text":{"type":"string"},"html":{"type":"string"},"sms_text":{"type":"string"},"from":{"type":"string"},"reply_to":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"201":{"description":"Template","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Template"}}}},"409":{"description":"Name already used"}}}},"/v1/templates/{name}":{"parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Read a template","responses":{"200":{"description":"Template"}}},"put":{"summary":"Update a template","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"},"subject":{"type":"string"},"text":{"type":"string"},"html":{"type":"string"},"sms_text":{"type":"string"},"from":{"type":"string"},"reply_to":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"Template"}}},"delete":{"summary":"Delete a template","responses":{"200":{"description":"Deleted"}}}},"/v1/templates/{name}/render":{"post":{"summary":"Preview a template with variables (no send)","parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"variables":{"type":"object"}}}}}},"responses":{"200":{"description":"Rendered subject/text/html/sms_text"}}}},"/v1/stats":{"get":{"summary":"Delivery statistics","parameters":[{"name":"from","in":"query","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","schema":{"type":"string","format":"date"}},{"name":"group_by","in":"query","schema":{"type":"string","enum":["day","channel","tag"]}}],"responses":{"200":{"description":"Totals and rows"}}}},"/v1/messages/batch":{"post":{"summary":"Send up to 100 messages in one call","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"messages":{"type":"array","maxItems":100,"items":{"oneOf":[{"$ref":"#/components/schemas/EmailInput"},{"$ref":"#/components/schemas/SmsInput"}]}}}}}}},"responses":{"202":{"description":"At least one accepted; per-entry results"},"400":{"description":"None accepted"}}}},"/v1/suppressions":{"get":{"summary":"List suppressed addresses","responses":{"200":{"description":"List"}}},"post":{"summary":"Suppress an address","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"},"detail":{"type":"string"}}}}}},"responses":{"201":{"description":"Added"}}}},"/v1/suppressions/{email}":{"parameters":[{"name":"email","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Read a suppression","responses":{"200":{"description":"Suppression"},"404":{"description":"Not suppressed"}}},"delete":{"summary":"Remove an address from the list","responses":{"200":{"description":"Removed"}}}}}}