{ "openapi": "3.1.0", "info": { "title": "PadiMail API", "version": "1.0.0" }, "servers": [ { "url": "https://api.padimail.app" } ], "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "pm_live_… or pm_test_…" }, "session": { "type": "apiKey", "in": "cookie", "name": "__Secure-neon-auth.session_token" } }, "schemas": { "BatchSendItem": { "type": "object", "properties": { "from": { "type": "string", "minLength": 3, "maxLength": 320, "example": "Acme Store " }, "to": { "anyOf": [ { "type": "string", "maxLength": 254, "format": "email", "example": "ada@example.com" }, { "type": "array", "items": { "type": "string", "maxLength": 254, "format": "email", "example": "ada@example.com" }, "maxItems": 50 } ] }, "cc": { "anyOf": [ { "type": "string", "maxLength": 254, "format": "email", "example": "ada@example.com" }, { "type": "array", "items": { "type": "string", "maxLength": 254, "format": "email", "example": "ada@example.com" }, "maxItems": 50 } ] }, "bcc": { "anyOf": [ { "type": "string", "maxLength": 254, "format": "email", "example": "ada@example.com" }, { "type": "array", "items": { "type": "string", "maxLength": 254, "format": "email", "example": "ada@example.com" }, "maxItems": 50 } ] }, "reply_to": { "anyOf": [ { "type": "string", "maxLength": 254, "format": "email", "example": "ada@example.com" }, { "type": "array", "items": { "type": "string", "maxLength": 254, "format": "email", "example": "ada@example.com" }, "maxItems": 50 } ] }, "subject": { "type": "string", "maxLength": 998 }, "html": { "type": "string" }, "text": { "type": "string" }, "template": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "variables": { "type": "object", "additionalProperties": {} } }, "required": [ "id" ] }, "stream": { "type": "string", "enum": [ "transactional", "marketing" ] }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,256}$" }, "value": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,256}$" } }, "required": [ "name", "value" ] }, "maxItems": 10 }, "quota_behavior": { "type": "string", "enum": [ "queue", "reject" ] }, "fallback": { "type": "boolean" } }, "required": [ "from", "to" ] }, "Account": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "account" ] }, "id": { "type": "string", "pattern": "^org_[0-9A-Za-z]+$", "example": "org_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S" }, "name": { "type": "string" }, "tier": { "type": [ "integer", "null" ] }, "status": { "type": "string", "enum": [ "active", "under_review", "paused", "suspended", "closed" ] }, "plan": { "type": "string" }, "country": { "type": "string" }, "timezone": { "type": "string" }, "quota_behavior": { "type": "string", "enum": [ "queue", "reject" ] }, "limits": { "type": "object", "properties": { "daily_limit": { "type": [ "integer", "null" ] }, "monthly_limit": { "type": [ "integer", "null" ] }, "daily_used": { "type": "integer" }, "monthly_used": { "type": "integer" }, "daily_resets_at": { "type": "string", "format": "date-time", "example": "2026-10-27T13:05:09Z" }, "monthly_resets_at": { "type": "string", "format": "date-time", "example": "2026-10-27T13:05:09Z" }, "waiting": { "type": "integer" } }, "required": [ "daily_limit", "monthly_limit", "daily_used", "monthly_used", "daily_resets_at", "monthly_resets_at", "waiting" ] }, "credits": { "type": "object", "properties": { "emails": { "type": "integer" }, "kobo": { "type": [ "integer", "null" ] }, "status": { "type": "string", "enum": [ "none", "ok", "low", "exhausted" ] } }, "required": [ "emails", "kobo", "status" ] } }, "required": [ "object", "id", "name", "tier", "status", "plan", "country", "timezone", "quota_behavior", "limits", "credits" ] }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "validation_error", "authentication_error", "payment_required", "permission_error", "not_found", "gone", "conflict", "unprocessable", "rate_limit_error", "not_implemented", "api_error" ] }, "code": { "type": "string" }, "message": { "type": "string" }, "fields": { "type": "object", "additionalProperties": { "type": "string" } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "index", "code", "message" ] } }, "doc_url": { "type": "string", "format": "uri" }, "request_id": { "type": "string" } }, "required": [ "type", "code", "message", "doc_url", "request_id" ] } }, "required": [ "error" ] }, "SendEmailResponse": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^em_[0-9A-Za-z]+$", "example": "em_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S" }, "status": { "type": "string", "enum": [ "queued", "scheduled", "deferred" ] }, "deferred_reason": { "type": "string", "enum": [ "daily_limit", "monthly_limit", "no_credits", "handle_warmup", "sandbox_limit" ] }, "deferred_until": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-10-27T13:05:09Z" }, "sent_via": { "type": "string", "enum": [ "padimail", "gmail_fallback" ] }, "from": { "type": "string" } }, "required": [ "id" ] }, "SendEmailRequest": { "type": "object", "properties": { "from": { "type": "string", "minLength": 3, "maxLength": 320, "example": "Acme Store " }, "to": { "anyOf": [ { "type": "string", "maxLength": 254, "format": "email", "example": "ada@example.com" }, { "type": "array", "items": { "type": "string", "maxLength": 254, "format": "email", "example": "ada@example.com" }, "maxItems": 50 } ] }, "cc": { "anyOf": [ { "type": "string", "maxLength": 254, "format": "email", "example": "ada@example.com" }, { "type": "array", "items": { "type": "string", "maxLength": 254, "format": "email", "example": "ada@example.com" }, "maxItems": 50 } ] }, "bcc": { "anyOf": [ { "type": "string", "maxLength": 254, "format": "email", "example": "ada@example.com" }, { "type": "array", "items": { "type": "string", "maxLength": 254, "format": "email", "example": "ada@example.com" }, "maxItems": 50 } ] }, "reply_to": { "anyOf": [ { "type": "string", "maxLength": 254, "format": "email", "example": "ada@example.com" }, { "type": "array", "items": { "type": "string", "maxLength": 254, "format": "email", "example": "ada@example.com" }, "maxItems": 50 } ] }, "subject": { "type": "string", "maxLength": 998 }, "html": { "type": "string" }, "text": { "type": "string" }, "template": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "variables": { "type": "object", "additionalProperties": {} } }, "required": [ "id" ] }, "stream": { "type": "string", "enum": [ "transactional", "marketing" ] }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "filename": { "type": "string", "minLength": 1, "maxLength": 255 }, "content": { "type": "string" }, "path": { "type": "string", "format": "uri" }, "content_type": { "type": "string" } }, "required": [ "filename" ] } }, "tags": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,256}$" }, "value": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,256}$" } }, "required": [ "name", "value" ] }, "maxItems": 10 }, "scheduled_at": { "type": "string", "format": "date-time", "example": "2026-10-27T13:05:09Z" }, "quota_behavior": { "type": "string", "enum": [ "queue", "reject" ] }, "fallback": { "type": "boolean" } }, "required": [ "from", "to" ] }, "EmailSummary": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^em_[0-9A-Za-z]+$", "example": "em_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S" }, "object": { "type": "string", "enum": [ "email" ] }, "created_at": { "type": "string", "format": "date-time", "example": "2026-10-27T13:05:09Z" }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "from": { "type": "string" }, "to": { "type": "array", "items": { "type": "string" } }, "subject": { "type": [ "string", "null" ] }, "stream": { "type": "string", "enum": [ "transactional", "marketing" ] }, "source": { "type": "string", "enum": [ "api", "smtp", "dashboard", "paste_send", "broadcast", "automation" ] }, "sender_kind": { "type": "string", "enum": [ "custom_domain", "shared_handle", "sandbox", "system", "gmail_fallback" ] }, "sent_via": { "type": "string", "enum": [ "padimail", "gmail_fallback" ] }, "status": { "type": "string", "enum": [ "queued", "scheduled", "deferred", "scanning", "held", "sending", "sent", "delivered", "delivery_delayed", "bounced", "complained", "suppressed", "rejected", "failed", "canceled" ] }, "scheduled_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-10-27T13:05:09Z" }, "deferred_reason": { "type": [ "string", "null" ], "enum": [ "daily_limit", "monthly_limit", "no_credits", "handle_warmup", "sandbox_limit", null ] }, "deferred_until": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-10-27T13:05:09Z" }, "tags": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,256}$" }, "value": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,256}$" } }, "required": [ "name", "value" ] } }, "recipient_count": { "type": "integer" } }, "required": [ "id", "object", "created_at", "mode", "from", "to", "subject", "stream", "source", "sender_kind", "sent_via", "status", "scheduled_at", "deferred_reason", "deferred_until", "tags", "recipient_count" ] }, "Email": { "allOf": [ { "$ref": "#/components/schemas/EmailSummary" }, { "type": "object", "properties": { "reply_to": { "type": "array", "items": { "type": "string" } }, "domain_id": { "type": [ "string", "null" ], "pattern": "^dom_[0-9A-Za-z]+$", "example": "dom_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S" }, "api_key_id": { "type": [ "string", "null" ] }, "template_id": { "type": [ "string", "null" ] }, "template_version": { "type": [ "integer", "null" ] }, "has_attachments": { "type": "boolean" }, "size_bytes": { "type": [ "integer", "null" ] }, "content_expires_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-10-27T13:05:09Z" }, "content_available": { "type": "boolean" }, "canceled_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-10-27T13:05:09Z" }, "recipients": { "type": "array", "items": { "$ref": "#/components/schemas/Recipient" } } }, "required": [ "reply_to", "domain_id", "api_key_id", "template_id", "template_version", "has_attachments", "size_bytes", "content_expires_at", "content_available", "canceled_at", "recipients" ] } ] }, "Recipient": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^rcp_[0-9A-Za-z]+$", "example": "rcp_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S" }, "address": { "type": "string", "maxLength": 254, "format": "email", "example": "ada@example.com" }, "kind": { "type": "string", "enum": [ "to", "cc", "bcc" ] }, "status": { "type": "string", "enum": [ "queued", "scheduled", "deferred", "scanning", "held", "sending", "sent", "delivered", "delivery_delayed", "bounced", "complained", "suppressed", "rejected", "failed", "canceled" ] }, "sent_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-10-27T13:05:09Z" }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-10-27T13:05:09Z" }, "opened_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-10-27T13:05:09Z" }, "clicked_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-10-27T13:05:09Z" }, "bounced_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-10-27T13:05:09Z" }, "complained_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-10-27T13:05:09Z" }, "bounce_type": { "type": [ "string", "null" ], "enum": [ "hard", "soft", "undetermined", null ] }, "status_detail": { "type": [ "string", "null" ] }, "open_count": { "type": "integer" }, "click_count": { "type": "integer" } }, "required": [ "id", "address", "kind", "status", "sent_at", "delivered_at", "opened_at", "clicked_at", "bounced_at", "complained_at", "bounce_type", "status_detail", "open_count", "click_count" ] }, "EmailEvent": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^evt_[0-9A-Za-z]+$", "example": "evt_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S" }, "type": { "type": "string", "enum": [ "queued", "scheduled", "deferred", "held", "released", "sent", "delivered", "delivery_delayed", "bounced", "complained", "opened", "clicked", "rejected", "failed", "suppressed", "canceled", "unsubscribed" ] }, "occurred_at": { "type": "string", "format": "date-time", "example": "2026-10-27T13:05:09Z" }, "email_id": { "type": "string", "pattern": "^em_[0-9A-Za-z]+$", "example": "em_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S" }, "recipient_id": { "type": [ "string", "null" ], "pattern": "^rcp_[0-9A-Za-z]+$", "example": "rcp_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S" }, "to": { "type": [ "string", "null" ] }, "data": { "type": "object", "additionalProperties": {} } }, "required": [ "id", "type", "occurred_at", "email_id", "recipient_id", "to", "data" ] }, "Domain": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^dom_[0-9A-Za-z]+$", "example": "dom_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S" }, "object": { "type": "string", "enum": [ "domain" ] }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "verified", "failed", "temporary_failure" ] }, "region": { "type": "string" }, "mail_from_subdomain": { "type": "string" }, "tracking_subdomain": { "type": [ "string", "null" ] }, "open_tracking": { "type": "boolean" }, "click_tracking": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-10-27T13:05:09Z" }, "verified_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-10-27T13:05:09Z" }, "last_checked_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-10-27T13:05:09Z" }, "records": { "type": "array", "items": { "$ref": "#/components/schemas/DnsRecord" } } }, "required": [ "id", "object", "name", "status", "region", "mail_from_subdomain", "tracking_subdomain", "open_tracking", "click_tracking", "created_at", "verified_at", "last_checked_at", "records" ] }, "DnsRecord": { "type": "object", "properties": { "purpose": { "type": "string", "enum": [ "dkim", "spf", "mail_from_mx", "mail_from_spf", "dmarc", "tracking_cname", "ownership_txt" ] }, "type": { "type": "string", "enum": [ "TXT", "CNAME", "MX" ] }, "host": { "type": "string" }, "value": { "type": "string" }, "priority": { "type": [ "integer", "null" ] }, "required": { "type": "boolean" }, "status": { "type": "string", "enum": [ "not_found", "mismatch", "verified" ] }, "found_value": { "type": [ "string", "null" ] }, "checked_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-10-27T13:05:09Z" } }, "required": [ "purpose", "type", "host", "value", "priority", "required", "status", "found_value", "checked_at" ] }, "CreatedApiKey": { "allOf": [ { "$ref": "#/components/schemas/ApiKey" }, { "type": "object", "properties": { "token": { "type": "string", "example": "pm_live_7Hq2…" } }, "required": [ "token" ] } ] }, "ApiKey": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^key_[0-9A-Za-z]+$", "example": "key_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S" }, "object": { "type": "string", "enum": [ "api_key" ] }, "name": { "type": "string" }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "permission": { "type": "string", "enum": [ "full_access", "sending_access" ] }, "domain_id": { "type": [ "string", "null" ], "pattern": "^dom_[0-9A-Za-z]+$", "example": "dom_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S" }, "prefix": { "type": "string", "example": "pm_live_7Hq2" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-10-27T13:05:09Z" }, "created_by": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time", "example": "2026-10-27T13:05:09Z" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-10-27T13:05:09Z" } }, "required": [ "id", "object", "name", "mode", "permission", "domain_id", "prefix", "last_used_at", "created_by", "created_at", "revoked_at" ] }, "Suppression": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^sup_[0-9A-Za-z]+$", "example": "sup_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S" }, "object": { "type": "string", "enum": [ "suppression" ] }, "address": { "type": "string", "maxLength": 254, "format": "email", "example": "ada@example.com" }, "reason": { "type": "string", "enum": [ "bounce", "complaint", "unsubscribe", "manual", "invalid" ] }, "stream": { "type": [ "string", "null" ], "enum": [ "transactional", "marketing", null ] }, "source_email_id": { "type": [ "string", "null" ], "pattern": "^em_[0-9A-Za-z]+$", "example": "em_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-10-27T13:05:09Z" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-10-27T13:05:09Z" } }, "required": [ "id", "object", "address", "reason", "stream", "source_email_id", "created_at", "expires_at" ] }, "Webhook": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^wh_[0-9A-Za-z]+$", "example": "wh_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S" }, "object": { "type": "string", "enum": [ "webhook" ] }, "mode": { "type": "string", "enum": [ "live", "test" ] }, "url": { "type": "string", "format": "uri" }, "description": { "type": [ "string", "null" ] }, "event_types": { "type": "array", "items": { "type": "string", "enum": [ "email.queued", "email.scheduled", "email.deferred", "email.sent", "email.delivered", "email.delivery_delayed", "email.bounced", "email.complained", "email.opened", "email.clicked", "email.suppressed", "email.held", "email.released", "email.rejected", "email.failed", "email.canceled", "domain.verified", "domain.failed", "account.paused", "account.resumed", "account.quota_reached", "account.usage_threshold", "account.usage_spike" ] } }, "format": { "type": "string", "enum": [ "padimail", "resend" ] }, "status": { "type": "string", "enum": [ "enabled", "disabled", "auto_disabled" ] }, "failing_since": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-10-27T13:05:09Z" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-10-27T13:05:09Z" } }, "required": [ "id", "object", "mode", "url", "description", "event_types", "format", "status", "failing_since", "created_at" ] }, "WebhookDelivery": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^whd_[0-9A-Za-z]+$", "example": "whd_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S" }, "webhook_id": { "type": "string", "pattern": "^wh_[0-9A-Za-z]+$", "example": "wh_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S" }, "event_id": { "type": "string", "pattern": "^evt_[0-9A-Za-z]+$", "example": "evt_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S" }, "event_type": { "type": "string" }, "attempt": { "type": "integer" }, "status": { "type": "string", "enum": [ "pending", "succeeded", "failed" ] }, "response_status": { "type": [ "integer", "null" ] }, "response_body_excerpt": { "type": [ "string", "null" ] }, "duration_ms": { "type": [ "integer", "null" ] }, "next_attempt_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-10-27T13:05:09Z" }, "created_at": { "type": "string", "format": "date-time", "example": "2026-10-27T13:05:09Z" } }, "required": [ "id", "webhook_id", "event_id", "event_type", "attempt", "status", "response_status", "response_body_excerpt", "duration_ms", "next_attempt_at", "created_at" ] }, "Template": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^tpl_[0-9A-Za-z]+$", "example": "tpl_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S" }, "object": { "type": "string", "enum": [ "template" ] }, "name": { "type": "string" }, "alias": { "type": [ "string", "null" ] }, "stream": { "type": "string", "enum": [ "transactional", "marketing" ] }, "current_version": { "type": [ "integer", "null" ] }, "created_at": { "type": "string", "format": "date-time", "example": "2026-10-27T13:05:09Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-10-27T13:05:09Z" }, "draft": { "$ref": "#/components/schemas/TemplateVersion" }, "published": { "$ref": "#/components/schemas/TemplateVersion" } }, "required": [ "id", "object", "name", "alias", "stream", "current_version", "created_at", "updated_at", "draft", "published" ] }, "TemplateVersion": { "type": [ "object", "null" ], "properties": { "version": { "type": "integer" }, "subject": { "type": [ "string", "null" ] }, "html": { "type": [ "string", "null" ] }, "text": { "type": [ "string", "null" ] }, "variables": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$" }, "type": { "type": "string", "enum": [ "string", "number", "boolean", "object", "array" ], "default": "string" }, "required": { "type": "boolean", "default": false }, "sample": {} }, "required": [ "name" ] } }, "created_by": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time", "example": "2026-10-27T13:05:09Z" }, "published_at": { "type": [ "string", "null" ], "format": "date-time", "example": "2026-10-27T13:05:09Z" } }, "required": [ "version", "subject", "html", "text", "variables", "created_by", "created_at", "published_at" ] } }, "parameters": {} }, "paths": { "/v1/health": { "get": { "tags": [ "Meta" ], "summary": "Health check (no key needed)", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "enum": [ true ] }, "service": { "type": "string", "enum": [ "padimail-api" ] }, "version": { "type": "string" }, "time": { "type": "string", "format": "date-time", "example": "2026-10-27T13:05:09Z" } }, "required": [ "ok", "service", "version", "time" ] } } } } }, "x-codeSamples": [ { "lang": "JavaScript", "label": "Node SDK", "source": "import { PadiMail } from \"@padimail/node\";\n\nconst pm = new PadiMail(process.env.PADIMAIL_API_KEY);\n\nconst result = await pm.health();" }, { "lang": "Shell", "label": "cURL", "source": "curl 'https://api.padimail.app/v1/health' \\\n -H \"Authorization: Bearer $PADIMAIL_API_KEY\"" }, { "lang": "Python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.get(\n \"https://api.padimail.app/v1/health\",\n headers={\"Authorization\": f\"Bearer {os.environ['PADIMAIL_API_KEY']}\"},\n)\nresponse.raise_for_status()\nprint(response.json())" } ] } }, "/v1/account": { "get": { "tags": [ "Account" ], "summary": "Organisation, tier, plan, limits and credits", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited or over a limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "JavaScript", "label": "Node SDK", "source": "import { PadiMail } from \"@padimail/node\";\n\nconst pm = new PadiMail(process.env.PADIMAIL_API_KEY);\n\nconst result = await pm.account.get();" }, { "lang": "Shell", "label": "cURL", "source": "curl 'https://api.padimail.app/v1/account' \\\n -H \"Authorization: Bearer $PADIMAIL_API_KEY\"" }, { "lang": "Python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.get(\n \"https://api.padimail.app/v1/account\",\n headers={\"Authorization\": f\"Bearer {os.environ['PADIMAIL_API_KEY']}\"},\n)\nresponse.raise_for_status()\nprint(response.json())" } ] } }, "/v1/usage": { "get": { "tags": [ "Account" ], "summary": "Emails sent, delivered, bounced, complained, opened and clicked", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "format": "date" }, "required": false, "name": "from", "in": "query" }, { "schema": { "type": "string", "format": "date" }, "required": false, "name": "to", "in": "query" }, { "schema": { "type": "string", "enum": [ "day", "stream" ], "default": "day" }, "required": false, "name": "group_by", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string", "example": "2026-10-27" }, "stream": { "type": "string", "enum": [ "transactional", "marketing" ] }, "emails_sent": { "type": "integer" }, "delivered": { "type": "integer" }, "bounced": { "type": "integer" }, "complained": { "type": "integer" }, "opened": { "type": "integer" }, "clicked": { "type": "integer" } }, "required": [ "day", "emails_sent", "delivered", "bounced", "complained", "opened", "clicked" ] } } }, "required": [ "data" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited or over a limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "JavaScript", "label": "Node SDK", "source": "import { PadiMail } from \"@padimail/node\";\n\nconst pm = new PadiMail(process.env.PADIMAIL_API_KEY);\n\nconst result = await pm.account.usage({ from: \"2026-10-01\", to: \"2026-10-31\" });" }, { "lang": "Shell", "label": "cURL", "source": "curl 'https://api.padimail.app/v1/usage?from=2026-10-01&to=2026-10-31' \\\n -H \"Authorization: Bearer $PADIMAIL_API_KEY\"" }, { "lang": "Python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.get(\n \"https://api.padimail.app/v1/usage\",\n headers={\"Authorization\": f\"Bearer {os.environ['PADIMAIL_API_KEY']}\"},\n params={ \"from\": \"2026-10-01\", \"to\": \"2026-10-31\" },\n)\nresponse.raise_for_status()\nprint(response.json())" } ] } }, "/v1/emails": { "post": { "tags": [ "Emails" ], "summary": "Send an email", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "maxLength": 255 }, "required": false, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendEmailRequest" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendEmailResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited or over a limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "JavaScript", "label": "Node SDK", "source": "import { PadiMail } from \"@padimail/node\";\n\nconst pm = new PadiMail(process.env.PADIMAIL_API_KEY);\n\nconst result = await pm.emails.send({\n from: \"Acme Store \",\n to: [\"ada@example.com\"],\n subject: \"Your receipt #1042\",\n html: \"

Thanks for your order.

\",\n tags: [{ name: \"category\", value: \"receipt\" }],\n});" }, { "lang": "Shell", "label": "cURL", "source": "curl -X POST 'https://api.padimail.app/v1/emails' \\\n -H \"Authorization: Bearer $PADIMAIL_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"from\": \"Acme Store \",\n \"to\": [\"ada@example.com\"],\n \"subject\": \"Your receipt #1042\",\n \"html\": \"

Thanks for your order.

\",\n \"tags\": [{ \"name\": \"category\", \"value\": \"receipt\" }]\n}'" }, { "lang": "Python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.post(\n \"https://api.padimail.app/v1/emails\",\n headers={\"Authorization\": f\"Bearer {os.environ['PADIMAIL_API_KEY']}\"},\n json={\n \"from\": \"Acme Store \",\n \"to\": [\"ada@example.com\"],\n \"subject\": \"Your receipt #1042\",\n \"html\": \"

Thanks for your order.

\",\n \"tags\": [{ \"name\": \"category\", \"value\": \"receipt\" }],\n },\n)\nresponse.raise_for_status()\nprint(response.json())" } ] }, "get": { "tags": [ "Emails" ], "summary": "List emails", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "after", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "before", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "example": "2026-10-27T13:05:09Z" }, "required": false, "name": "created_after", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "example": "2026-10-27T13:05:09Z" }, "required": false, "name": "created_before", "in": "query" }, { "schema": { "type": "string", "enum": [ "queued", "scheduled", "deferred", "scanning", "held", "sending", "sent", "delivered", "delivery_delayed", "bounced", "complained", "suppressed", "rejected", "failed", "canceled" ] }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "string", "maxLength": 254, "format": "email", "example": "ada@example.com" }, "required": false, "name": "to", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "from", "in": "query" }, { "schema": { "type": "string", "pattern": "^dom_[0-9A-Za-z]+$", "example": "dom_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S" }, "required": false, "name": "domain_id", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "tag", "in": "query" }, { "schema": { "type": "string", "enum": [ "transactional", "marketing" ] }, "required": false, "name": "stream", "in": "query" }, { "schema": { "type": "string", "enum": [ "api", "smtp", "dashboard", "paste_send", "broadcast", "automation" ] }, "required": false, "name": "source", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EmailSummary" } }, "has_more": { "type": "boolean" }, "next": { "type": [ "string", "null" ] } }, "required": [ "data", "has_more", "next" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited or over a limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "JavaScript", "label": "Node SDK", "source": "import { PadiMail } from \"@padimail/node\";\n\nconst pm = new PadiMail(process.env.PADIMAIL_API_KEY);\n\nconst result = await pm.emails.list({ status: \"delivered\", limit: 20 });" }, { "lang": "Shell", "label": "cURL", "source": "curl 'https://api.padimail.app/v1/emails?status=delivered&limit=20' \\\n -H \"Authorization: Bearer $PADIMAIL_API_KEY\"" }, { "lang": "Python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.get(\n \"https://api.padimail.app/v1/emails\",\n headers={\"Authorization\": f\"Bearer {os.environ['PADIMAIL_API_KEY']}\"},\n params={ \"status\": \"delivered\", \"limit\": 20 },\n)\nresponse.raise_for_status()\nprint(response.json())" } ] } }, "/v1/emails/batch": { "post": { "tags": [ "Emails" ], "summary": "Send up to 100 emails", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "enum": [ "strict", "permissive" ] }, "required": false, "name": "validation", "in": "query" }, { "schema": { "type": "string", "maxLength": 255 }, "required": false, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BatchSendItem" }, "minItems": 1, "maxItems": 100 } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SendEmailResponse" } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "index": { "type": "integer" }, "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "index", "code", "message" ] } } }, "required": [ "data" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited or over a limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "JavaScript", "label": "Node SDK", "source": "import { PadiMail } from \"@padimail/node\";\n\nconst pm = new PadiMail(process.env.PADIMAIL_API_KEY);\n\nconst result = await pm.emails.batch([\n {\n from: \"Acme Store \",\n to: [\"ada@example.com\"],\n subject: \"Your receipt #1042\",\n html: \"

Thanks, Ada.

\",\n },\n {\n from: \"Acme Store \",\n to: [\"chidi@example.com\"],\n subject: \"Your receipt #1043\",\n html: \"

Thanks, Chidi.

\",\n },\n]);" }, { "lang": "Shell", "label": "cURL", "source": "curl -X POST 'https://api.padimail.app/v1/emails/batch' \\\n -H \"Authorization: Bearer $PADIMAIL_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '[\n {\n \"from\": \"Acme Store \",\n \"to\": [\"ada@example.com\"],\n \"subject\": \"Your receipt #1042\",\n \"html\": \"

Thanks, Ada.

\"\n },\n {\n \"from\": \"Acme Store \",\n \"to\": [\"chidi@example.com\"],\n \"subject\": \"Your receipt #1043\",\n \"html\": \"

Thanks, Chidi.

\"\n }\n]'" }, { "lang": "Python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.post(\n \"https://api.padimail.app/v1/emails/batch\",\n headers={\"Authorization\": f\"Bearer {os.environ['PADIMAIL_API_KEY']}\"},\n json=[\n {\n \"from\": \"Acme Store \",\n \"to\": [\"ada@example.com\"],\n \"subject\": \"Your receipt #1042\",\n \"html\": \"

Thanks, Ada.

\",\n },\n {\n \"from\": \"Acme Store \",\n \"to\": [\"chidi@example.com\"],\n \"subject\": \"Your receipt #1043\",\n \"html\": \"

Thanks, Chidi.

\",\n },\n ],\n)\nresponse.raise_for_status()\nprint(response.json())" } ] } }, "/v1/emails/{id}": { "get": { "tags": [ "Emails" ], "summary": "Get an email", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^em_[0-9A-Za-z]+$", "example": "em_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Email" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited or over a limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "JavaScript", "label": "Node SDK", "source": "import { PadiMail } from \"@padimail/node\";\n\nconst pm = new PadiMail(process.env.PADIMAIL_API_KEY);\n\nconst result = await pm.emails.get(\"em_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S\");" }, { "lang": "Shell", "label": "cURL", "source": "curl 'https://api.padimail.app/v1/emails/em_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S' \\\n -H \"Authorization: Bearer $PADIMAIL_API_KEY\"" }, { "lang": "Python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.get(\n \"https://api.padimail.app/v1/emails/em_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S\",\n headers={\"Authorization\": f\"Bearer {os.environ['PADIMAIL_API_KEY']}\"},\n)\nresponse.raise_for_status()\nprint(response.json())" } ] }, "patch": { "tags": [ "Emails" ], "summary": "Reschedule a scheduled email", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^em_[0-9A-Za-z]+$", "example": "em_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "scheduled_at": { "type": "string", "format": "date-time", "example": "2026-10-27T13:05:09Z" } }, "required": [ "scheduled_at" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Email" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited or over a limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "JavaScript", "label": "Node SDK", "source": "import { PadiMail } from \"@padimail/node\";\n\nconst pm = new PadiMail(process.env.PADIMAIL_API_KEY);\n\nconst result = await pm.emails.update(\"em_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S\", { scheduled_at: \"2026-10-28T09:00:00+01:00\" });" }, { "lang": "Shell", "label": "cURL", "source": "curl -X PATCH 'https://api.padimail.app/v1/emails/em_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S' \\\n -H \"Authorization: Bearer $PADIMAIL_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{ \"scheduled_at\": \"2026-10-28T09:00:00+01:00\" }'" }, { "lang": "Python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.patch(\n \"https://api.padimail.app/v1/emails/em_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S\",\n headers={\"Authorization\": f\"Bearer {os.environ['PADIMAIL_API_KEY']}\"},\n json={ \"scheduled_at\": \"2026-10-28T09:00:00+01:00\" },\n)\nresponse.raise_for_status()\nprint(response.json())" } ] } }, "/v1/emails/{id}/events": { "get": { "tags": [ "Emails" ], "summary": "An email's events, oldest first", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^em_[0-9A-Za-z]+$", "example": "em_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EmailEvent" } } }, "required": [ "data" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited or over a limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "JavaScript", "label": "Node SDK", "source": "import { PadiMail } from \"@padimail/node\";\n\nconst pm = new PadiMail(process.env.PADIMAIL_API_KEY);\n\nconst result = await pm.emails.events(\"em_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S\");" }, { "lang": "Shell", "label": "cURL", "source": "curl 'https://api.padimail.app/v1/emails/em_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S/events' \\\n -H \"Authorization: Bearer $PADIMAIL_API_KEY\"" }, { "lang": "Python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.get(\n \"https://api.padimail.app/v1/emails/em_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S/events\",\n headers={\"Authorization\": f\"Bearer {os.environ['PADIMAIL_API_KEY']}\"},\n)\nresponse.raise_for_status()\nprint(response.json())" } ] } }, "/v1/emails/{id}/content": { "get": { "tags": [ "Emails" ], "summary": "An email's content while it is retained", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^em_[0-9A-Za-z]+$", "example": "em_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "html": { "type": [ "string", "null" ] }, "text": { "type": [ "string", "null" ] }, "headers": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "html", "text", "headers" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "410": { "description": "Content expired", "content": { "application/json": { "schema": {} } } }, "429": { "description": "Rate limited or over a limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "JavaScript", "label": "Node SDK", "source": "import { PadiMail } from \"@padimail/node\";\n\nconst pm = new PadiMail(process.env.PADIMAIL_API_KEY);\n\nconst result = await pm.emails.content(\"em_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S\");" }, { "lang": "Shell", "label": "cURL", "source": "curl 'https://api.padimail.app/v1/emails/em_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S/content' \\\n -H \"Authorization: Bearer $PADIMAIL_API_KEY\"" }, { "lang": "Python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.get(\n \"https://api.padimail.app/v1/emails/em_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S/content\",\n headers={\"Authorization\": f\"Bearer {os.environ['PADIMAIL_API_KEY']}\"},\n)\nresponse.raise_for_status()\nprint(response.json())" } ] } }, "/v1/emails/{id}/cancel": { "post": { "tags": [ "Emails" ], "summary": "Cancel a scheduled, waiting or held email", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^em_[0-9A-Za-z]+$", "example": "em_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^em_[0-9A-Za-z]+$", "example": "em_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S" }, "object": { "type": "string", "enum": [ "email" ] }, "status": { "type": "string", "enum": [ "canceled" ] } }, "required": [ "id", "object", "status" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited or over a limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "JavaScript", "label": "Node SDK", "source": "import { PadiMail } from \"@padimail/node\";\n\nconst pm = new PadiMail(process.env.PADIMAIL_API_KEY);\n\nconst result = await pm.emails.cancel(\"em_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S\");" }, { "lang": "Shell", "label": "cURL", "source": "curl -X POST 'https://api.padimail.app/v1/emails/em_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S/cancel' \\\n -H \"Authorization: Bearer $PADIMAIL_API_KEY\"" }, { "lang": "Python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.post(\n \"https://api.padimail.app/v1/emails/em_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S/cancel\",\n headers={\"Authorization\": f\"Bearer {os.environ['PADIMAIL_API_KEY']}\"},\n)\nresponse.raise_for_status()\nprint(response.json())" } ] } }, "/v1/domains": { "post": { "tags": [ "Domains" ], "summary": "Add a domain", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "maxLength": 255 }, "required": false, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 3, "maxLength": 253, "pattern": "^(?!-)[a-z0-9-]+(\\.[a-z0-9-]+)+$/i" }, "region": { "type": "string", "default": "default" }, "open_tracking": { "type": "boolean" }, "click_tracking": { "type": "boolean" }, "mail_from_subdomain": { "type": "string", "pattern": "^[a-z0-9-]{1,63}$" } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Domain" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited or over a limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "JavaScript", "label": "Node SDK", "source": "import { PadiMail } from \"@padimail/node\";\n\nconst pm = new PadiMail(process.env.PADIMAIL_API_KEY);\n\nconst result = await pm.domains.create({ name: \"acme.ng\" });" }, { "lang": "Shell", "label": "cURL", "source": "curl -X POST 'https://api.padimail.app/v1/domains' \\\n -H \"Authorization: Bearer $PADIMAIL_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{ \"name\": \"acme.ng\" }'" }, { "lang": "Python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.post(\n \"https://api.padimail.app/v1/domains\",\n headers={\"Authorization\": f\"Bearer {os.environ['PADIMAIL_API_KEY']}\"},\n json={ \"name\": \"acme.ng\" },\n)\nresponse.raise_for_status()\nprint(response.json())" } ] }, "get": { "tags": [ "Domains" ], "summary": "List domains", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "after", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "before", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Domain" } }, "has_more": { "type": "boolean" }, "next": { "type": [ "string", "null" ] } }, "required": [ "data", "has_more", "next" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited or over a limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "JavaScript", "label": "Node SDK", "source": "import { PadiMail } from \"@padimail/node\";\n\nconst pm = new PadiMail(process.env.PADIMAIL_API_KEY);\n\nconst result = await pm.domains.list();" }, { "lang": "Shell", "label": "cURL", "source": "curl 'https://api.padimail.app/v1/domains' \\\n -H \"Authorization: Bearer $PADIMAIL_API_KEY\"" }, { "lang": "Python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.get(\n \"https://api.padimail.app/v1/domains\",\n headers={\"Authorization\": f\"Bearer {os.environ['PADIMAIL_API_KEY']}\"},\n)\nresponse.raise_for_status()\nprint(response.json())" } ] } }, "/v1/domains/{id}": { "get": { "tags": [ "Domains" ], "summary": "Get a domain with its DNS records", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^dom_[0-9A-Za-z]+$", "example": "dom_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Domain" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited or over a limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "JavaScript", "label": "Node SDK", "source": "import { PadiMail } from \"@padimail/node\";\n\nconst pm = new PadiMail(process.env.PADIMAIL_API_KEY);\n\nconst result = await pm.domains.get(\"dom_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S\");" }, { "lang": "Shell", "label": "cURL", "source": "curl 'https://api.padimail.app/v1/domains/dom_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S' \\\n -H \"Authorization: Bearer $PADIMAIL_API_KEY\"" }, { "lang": "Python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.get(\n \"https://api.padimail.app/v1/domains/dom_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S\",\n headers={\"Authorization\": f\"Bearer {os.environ['PADIMAIL_API_KEY']}\"},\n)\nresponse.raise_for_status()\nprint(response.json())" } ] }, "patch": { "tags": [ "Domains" ], "summary": "Change tracking settings", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^dom_[0-9A-Za-z]+$", "example": "dom_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "open_tracking": { "type": "boolean" }, "click_tracking": { "type": "boolean" }, "tracking_subdomain": { "type": [ "string", "null" ], "pattern": "^[a-z0-9-]{1,63}$" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Domain" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited or over a limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "JavaScript", "label": "Node SDK", "source": "import { PadiMail } from \"@padimail/node\";\n\nconst pm = new PadiMail(process.env.PADIMAIL_API_KEY);\n\nconst result = await pm.domains.update(\"dom_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S\", { open_tracking: true, click_tracking: true });" }, { "lang": "Shell", "label": "cURL", "source": "curl -X PATCH 'https://api.padimail.app/v1/domains/dom_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S' \\\n -H \"Authorization: Bearer $PADIMAIL_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{ \"open_tracking\": true, \"click_tracking\": true }'" }, { "lang": "Python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.patch(\n \"https://api.padimail.app/v1/domains/dom_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S\",\n headers={\"Authorization\": f\"Bearer {os.environ['PADIMAIL_API_KEY']}\"},\n json={ \"open_tracking\": True, \"click_tracking\": True },\n)\nresponse.raise_for_status()\nprint(response.json())" } ] }, "delete": { "tags": [ "Domains" ], "summary": "Delete a domain; its scheduled emails are canceled", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^dom_[0-9A-Za-z]+$", "example": "dom_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "deleted": { "type": "boolean", "enum": [ true ] } }, "required": [ "id", "object", "deleted" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited or over a limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "JavaScript", "label": "Node SDK", "source": "import { PadiMail } from \"@padimail/node\";\n\nconst pm = new PadiMail(process.env.PADIMAIL_API_KEY);\n\nconst result = await pm.domains.remove(\"dom_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S\");" }, { "lang": "Shell", "label": "cURL", "source": "curl -X DELETE 'https://api.padimail.app/v1/domains/dom_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S' \\\n -H \"Authorization: Bearer $PADIMAIL_API_KEY\"" }, { "lang": "Python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.delete(\n \"https://api.padimail.app/v1/domains/dom_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S\",\n headers={\"Authorization\": f\"Bearer {os.environ['PADIMAIL_API_KEY']}\"},\n)\nresponse.raise_for_status()\nprint(response.json())" } ] } }, "/v1/domains/{id}/verify": { "post": { "tags": [ "Domains" ], "summary": "Check the DNS records now (at most once a minute)", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^dom_[0-9A-Za-z]+$", "example": "dom_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Domain" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited or over a limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "JavaScript", "label": "Node SDK", "source": "import { PadiMail } from \"@padimail/node\";\n\nconst pm = new PadiMail(process.env.PADIMAIL_API_KEY);\n\nconst result = await pm.domains.verify(\"dom_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S\");" }, { "lang": "Shell", "label": "cURL", "source": "curl -X POST 'https://api.padimail.app/v1/domains/dom_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S/verify' \\\n -H \"Authorization: Bearer $PADIMAIL_API_KEY\"" }, { "lang": "Python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.post(\n \"https://api.padimail.app/v1/domains/dom_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S/verify\",\n headers={\"Authorization\": f\"Bearer {os.environ['PADIMAIL_API_KEY']}\"},\n)\nresponse.raise_for_status()\nprint(response.json())" } ] } }, "/v1/api-keys": { "post": { "tags": [ "API keys" ], "summary": "Create an API key (the token is shown once)", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "maxLength": 255 }, "required": false, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "mode": { "type": "string", "enum": [ "live", "test" ], "default": "live" }, "permission": { "type": "string", "enum": [ "full_access", "sending_access" ], "description": "full_access when left out, or sending_access when domain_id is set." }, "domain_id": { "type": [ "string", "null" ], "pattern": "^dom_[0-9A-Za-z]+$", "example": "dom_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S", "description": "Restrict a sending_access key to one domain. Not allowed with full_access." } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedApiKey" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited or over a limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "JavaScript", "label": "Node SDK", "source": "import { PadiMail } from \"@padimail/node\";\n\nconst pm = new PadiMail(process.env.PADIMAIL_API_KEY);\n\nconst result = await pm.apiKeys.create({ name: \"Production server\", permission: \"sending_access\" });" }, { "lang": "Shell", "label": "cURL", "source": "curl -X POST 'https://api.padimail.app/v1/api-keys' \\\n -H \"Authorization: Bearer $PADIMAIL_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{ \"name\": \"Production server\", \"permission\": \"sending_access\" }'" }, { "lang": "Python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.post(\n \"https://api.padimail.app/v1/api-keys\",\n headers={\"Authorization\": f\"Bearer {os.environ['PADIMAIL_API_KEY']}\"},\n json={ \"name\": \"Production server\", \"permission\": \"sending_access\" },\n)\nresponse.raise_for_status()\nprint(response.json())" } ] }, "get": { "tags": [ "API keys" ], "summary": "List API keys", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "after", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "before", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } }, "has_more": { "type": "boolean" }, "next": { "type": [ "string", "null" ] } }, "required": [ "data", "has_more", "next" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited or over a limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "JavaScript", "label": "Node SDK", "source": "import { PadiMail } from \"@padimail/node\";\n\nconst pm = new PadiMail(process.env.PADIMAIL_API_KEY);\n\nconst result = await pm.apiKeys.list();" }, { "lang": "Shell", "label": "cURL", "source": "curl 'https://api.padimail.app/v1/api-keys' \\\n -H \"Authorization: Bearer $PADIMAIL_API_KEY\"" }, { "lang": "Python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.get(\n \"https://api.padimail.app/v1/api-keys\",\n headers={\"Authorization\": f\"Bearer {os.environ['PADIMAIL_API_KEY']}\"},\n)\nresponse.raise_for_status()\nprint(response.json())" } ] } }, "/v1/api-keys/{id}": { "delete": { "tags": [ "API keys" ], "summary": "Revoke an API key (stops working within 60 s)", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^key_[0-9A-Za-z]+$", "example": "key_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "deleted": { "type": "boolean", "enum": [ true ] } }, "required": [ "id", "object", "deleted" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited or over a limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "JavaScript", "label": "Node SDK", "source": "import { PadiMail } from \"@padimail/node\";\n\nconst pm = new PadiMail(process.env.PADIMAIL_API_KEY);\n\nconst result = await pm.apiKeys.remove(\"key_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S\");" }, { "lang": "Shell", "label": "cURL", "source": "curl -X DELETE 'https://api.padimail.app/v1/api-keys/key_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S' \\\n -H \"Authorization: Bearer $PADIMAIL_API_KEY\"" }, { "lang": "Python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.delete(\n \"https://api.padimail.app/v1/api-keys/key_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S\",\n headers={\"Authorization\": f\"Bearer {os.environ['PADIMAIL_API_KEY']}\"},\n)\nresponse.raise_for_status()\nprint(response.json())" } ] } }, "/v1/suppressions": { "get": { "tags": [ "Suppressions" ], "summary": "List suppressions", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "after", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "before", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "address", "in": "query" }, { "schema": { "type": "string", "enum": [ "bounce", "complaint", "unsubscribe", "manual", "invalid" ] }, "required": false, "name": "reason", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Suppression" } }, "has_more": { "type": "boolean" }, "next": { "type": [ "string", "null" ] } }, "required": [ "data", "has_more", "next" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited or over a limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "JavaScript", "label": "Node SDK", "source": "import { PadiMail } from \"@padimail/node\";\n\nconst pm = new PadiMail(process.env.PADIMAIL_API_KEY);\n\nconst result = await pm.suppressions.list({ reason: \"bounce\" });" }, { "lang": "Shell", "label": "cURL", "source": "curl 'https://api.padimail.app/v1/suppressions?reason=bounce' \\\n -H \"Authorization: Bearer $PADIMAIL_API_KEY\"" }, { "lang": "Python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.get(\n \"https://api.padimail.app/v1/suppressions\",\n headers={\"Authorization\": f\"Bearer {os.environ['PADIMAIL_API_KEY']}\"},\n params={ \"reason\": \"bounce\" },\n)\nresponse.raise_for_status()\nprint(response.json())" } ] }, "post": { "tags": [ "Suppressions" ], "summary": "Suppress an address (reason manual)", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "maxLength": 255 }, "required": false, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "address": { "type": "string", "maxLength": 254, "format": "email", "example": "ada@example.com" }, "stream": { "type": [ "string", "null" ], "enum": [ "transactional", "marketing", null ] } }, "required": [ "address" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Suppression" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited or over a limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "JavaScript", "label": "Node SDK", "source": "import { PadiMail } from \"@padimail/node\";\n\nconst pm = new PadiMail(process.env.PADIMAIL_API_KEY);\n\nconst result = await pm.suppressions.create({ address: \"ada@example.com\" });" }, { "lang": "Shell", "label": "cURL", "source": "curl -X POST 'https://api.padimail.app/v1/suppressions' \\\n -H \"Authorization: Bearer $PADIMAIL_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{ \"address\": \"ada@example.com\" }'" }, { "lang": "Python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.post(\n \"https://api.padimail.app/v1/suppressions\",\n headers={\"Authorization\": f\"Bearer {os.environ['PADIMAIL_API_KEY']}\"},\n json={ \"address\": \"ada@example.com\" },\n)\nresponse.raise_for_status()\nprint(response.json())" } ] } }, "/v1/suppressions/{id}": { "delete": { "tags": [ "Suppressions" ], "summary": "Remove a suppression (not for complaints)", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^sup_[0-9A-Za-z]+$", "example": "sup_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "deleted": { "type": "boolean", "enum": [ true ] } }, "required": [ "id", "object", "deleted" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited or over a limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "JavaScript", "label": "Node SDK", "source": "import { PadiMail } from \"@padimail/node\";\n\nconst pm = new PadiMail(process.env.PADIMAIL_API_KEY);\n\nconst result = await pm.suppressions.remove(\"sup_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S\");" }, { "lang": "Shell", "label": "cURL", "source": "curl -X DELETE 'https://api.padimail.app/v1/suppressions/sup_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S' \\\n -H \"Authorization: Bearer $PADIMAIL_API_KEY\"" }, { "lang": "Python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.delete(\n \"https://api.padimail.app/v1/suppressions/sup_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S\",\n headers={\"Authorization\": f\"Bearer {os.environ['PADIMAIL_API_KEY']}\"},\n)\nresponse.raise_for_status()\nprint(response.json())" } ] } }, "/v1/webhooks": { "post": { "tags": [ "Webhooks" ], "summary": "Add a webhook endpoint", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "maxLength": 255 }, "required": false, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "description": { "type": "string", "maxLength": 500 }, "event_types": { "type": "array", "items": { "type": "string", "enum": [ "email.queued", "email.scheduled", "email.deferred", "email.sent", "email.delivered", "email.delivery_delayed", "email.bounced", "email.complained", "email.opened", "email.clicked", "email.suppressed", "email.held", "email.released", "email.rejected", "email.failed", "email.canceled", "domain.verified", "domain.failed", "account.paused", "account.resumed", "account.quota_reached", "account.usage_threshold", "account.usage_spike" ] }, "minItems": 1 }, "format": { "type": "string", "enum": [ "padimail", "resend" ] }, "mode": { "type": "string", "enum": [ "live", "test" ] } }, "required": [ "url", "event_types" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "type": "object", "properties": { "secret": { "type": "string", "example": "whsec_…" } }, "required": [ "secret" ] } ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited or over a limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "JavaScript", "label": "Node SDK", "source": "import { PadiMail } from \"@padimail/node\";\n\nconst pm = new PadiMail(process.env.PADIMAIL_API_KEY);\n\nconst result = await pm.webhooks.create({\n url: \"https://acme.ng/webhooks/padimail\",\n event_types: [\"email.delivered\", \"email.bounced\", \"email.complained\"],\n});" }, { "lang": "Shell", "label": "cURL", "source": "curl -X POST 'https://api.padimail.app/v1/webhooks' \\\n -H \"Authorization: Bearer $PADIMAIL_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"url\": \"https://acme.ng/webhooks/padimail\",\n \"event_types\": [\"email.delivered\", \"email.bounced\", \"email.complained\"]\n}'" }, { "lang": "Python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.post(\n \"https://api.padimail.app/v1/webhooks\",\n headers={\"Authorization\": f\"Bearer {os.environ['PADIMAIL_API_KEY']}\"},\n json={\n \"url\": \"https://acme.ng/webhooks/padimail\",\n \"event_types\": [\"email.delivered\", \"email.bounced\", \"email.complained\"],\n },\n)\nresponse.raise_for_status()\nprint(response.json())" } ] }, "get": { "tags": [ "Webhooks" ], "summary": "List webhook endpoints", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "after", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "before", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } }, "has_more": { "type": "boolean" }, "next": { "type": [ "string", "null" ] } }, "required": [ "data", "has_more", "next" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited or over a limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "JavaScript", "label": "Node SDK", "source": "import { PadiMail } from \"@padimail/node\";\n\nconst pm = new PadiMail(process.env.PADIMAIL_API_KEY);\n\nconst result = await pm.webhooks.list();" }, { "lang": "Shell", "label": "cURL", "source": "curl 'https://api.padimail.app/v1/webhooks' \\\n -H \"Authorization: Bearer $PADIMAIL_API_KEY\"" }, { "lang": "Python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.get(\n \"https://api.padimail.app/v1/webhooks\",\n headers={\"Authorization\": f\"Bearer {os.environ['PADIMAIL_API_KEY']}\"},\n)\nresponse.raise_for_status()\nprint(response.json())" } ] } }, "/v1/webhooks/{id}": { "get": { "tags": [ "Webhooks" ], "summary": "Get a webhook endpoint", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^wh_[0-9A-Za-z]+$", "example": "wh_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited or over a limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "JavaScript", "label": "Node SDK", "source": "import { PadiMail } from \"@padimail/node\";\n\nconst pm = new PadiMail(process.env.PADIMAIL_API_KEY);\n\nconst result = await pm.webhooks.get(\"wh_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S\");" }, { "lang": "Shell", "label": "cURL", "source": "curl 'https://api.padimail.app/v1/webhooks/wh_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S' \\\n -H \"Authorization: Bearer $PADIMAIL_API_KEY\"" }, { "lang": "Python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.get(\n \"https://api.padimail.app/v1/webhooks/wh_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S\",\n headers={\"Authorization\": f\"Bearer {os.environ['PADIMAIL_API_KEY']}\"},\n)\nresponse.raise_for_status()\nprint(response.json())" } ] }, "patch": { "tags": [ "Webhooks" ], "summary": "Update a webhook endpoint", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^wh_[0-9A-Za-z]+$", "example": "wh_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "description": { "type": [ "string", "null" ], "maxLength": 500 }, "event_types": { "type": "array", "items": { "type": "string", "enum": [ "email.queued", "email.scheduled", "email.deferred", "email.sent", "email.delivered", "email.delivery_delayed", "email.bounced", "email.complained", "email.opened", "email.clicked", "email.suppressed", "email.held", "email.released", "email.rejected", "email.failed", "email.canceled", "domain.verified", "domain.failed", "account.paused", "account.resumed", "account.quota_reached", "account.usage_threshold", "account.usage_spike" ] }, "minItems": 1 }, "format": { "type": "string", "enum": [ "padimail", "resend" ] }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited or over a limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "JavaScript", "label": "Node SDK", "source": "import { PadiMail } from \"@padimail/node\";\n\nconst pm = new PadiMail(process.env.PADIMAIL_API_KEY);\n\nconst result = await pm.webhooks.update(\"wh_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S\", { status: \"disabled\" });" }, { "lang": "Shell", "label": "cURL", "source": "curl -X PATCH 'https://api.padimail.app/v1/webhooks/wh_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S' \\\n -H \"Authorization: Bearer $PADIMAIL_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{ \"status\": \"disabled\" }'" }, { "lang": "Python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.patch(\n \"https://api.padimail.app/v1/webhooks/wh_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S\",\n headers={\"Authorization\": f\"Bearer {os.environ['PADIMAIL_API_KEY']}\"},\n json={ \"status\": \"disabled\" },\n)\nresponse.raise_for_status()\nprint(response.json())" } ] }, "delete": { "tags": [ "Webhooks" ], "summary": "Delete a webhook endpoint", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^wh_[0-9A-Za-z]+$", "example": "wh_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "deleted": { "type": "boolean", "enum": [ true ] } }, "required": [ "id", "object", "deleted" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited or over a limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "JavaScript", "label": "Node SDK", "source": "import { PadiMail } from \"@padimail/node\";\n\nconst pm = new PadiMail(process.env.PADIMAIL_API_KEY);\n\nconst result = await pm.webhooks.remove(\"wh_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S\");" }, { "lang": "Shell", "label": "cURL", "source": "curl -X DELETE 'https://api.padimail.app/v1/webhooks/wh_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S' \\\n -H \"Authorization: Bearer $PADIMAIL_API_KEY\"" }, { "lang": "Python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.delete(\n \"https://api.padimail.app/v1/webhooks/wh_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S\",\n headers={\"Authorization\": f\"Bearer {os.environ['PADIMAIL_API_KEY']}\"},\n)\nresponse.raise_for_status()\nprint(response.json())" } ] } }, "/v1/webhooks/{id}/rotate-secret": { "post": { "tags": [ "Webhooks" ], "summary": "Rotate the signing secret (the old one works for 24 h)", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^wh_[0-9A-Za-z]+$", "example": "wh_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "type": "object", "properties": { "secret": { "type": "string", "example": "whsec_…" } }, "required": [ "secret" ] } ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited or over a limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "JavaScript", "label": "Node SDK", "source": "import { PadiMail } from \"@padimail/node\";\n\nconst pm = new PadiMail(process.env.PADIMAIL_API_KEY);\n\nconst result = await pm.webhooks.rotateSecret(\"wh_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S\");" }, { "lang": "Shell", "label": "cURL", "source": "curl -X POST 'https://api.padimail.app/v1/webhooks/wh_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S/rotate-secret' \\\n -H \"Authorization: Bearer $PADIMAIL_API_KEY\"" }, { "lang": "Python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.post(\n \"https://api.padimail.app/v1/webhooks/wh_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S/rotate-secret\",\n headers={\"Authorization\": f\"Bearer {os.environ['PADIMAIL_API_KEY']}\"},\n)\nresponse.raise_for_status()\nprint(response.json())" } ] } }, "/v1/webhooks/{id}/test": { "post": { "tags": [ "Webhooks" ], "summary": "Send a test event", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^wh_[0-9A-Za-z]+$", "example": "wh_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event_type": { "type": "string", "enum": [ "email.queued", "email.scheduled", "email.deferred", "email.sent", "email.delivered", "email.delivery_delayed", "email.bounced", "email.complained", "email.opened", "email.clicked", "email.suppressed", "email.held", "email.released", "email.rejected", "email.failed", "email.canceled", "domain.verified", "domain.failed", "account.paused", "account.resumed", "account.quota_reached", "account.usage_threshold", "account.usage_spike" ] } }, "required": [ "event_type" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "delivery_id": { "type": "string", "pattern": "^whd_[0-9A-Za-z]+$", "example": "whd_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S" } }, "required": [ "delivery_id" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited or over a limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "JavaScript", "label": "Node SDK", "source": "import { PadiMail } from \"@padimail/node\";\n\nconst pm = new PadiMail(process.env.PADIMAIL_API_KEY);\n\nconst result = await pm.webhooks.test(\"wh_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S\", { event_type: \"email.delivered\" });" }, { "lang": "Shell", "label": "cURL", "source": "curl -X POST 'https://api.padimail.app/v1/webhooks/wh_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S/test' \\\n -H \"Authorization: Bearer $PADIMAIL_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{ \"event_type\": \"email.delivered\" }'" }, { "lang": "Python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.post(\n \"https://api.padimail.app/v1/webhooks/wh_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S/test\",\n headers={\"Authorization\": f\"Bearer {os.environ['PADIMAIL_API_KEY']}\"},\n json={ \"event_type\": \"email.delivered\" },\n)\nresponse.raise_for_status()\nprint(response.json())" } ] } }, "/v1/webhooks/{id}/deliveries": { "get": { "tags": [ "Webhooks" ], "summary": "List deliveries (kept 30 days)", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^wh_[0-9A-Za-z]+$", "example": "wh_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "after", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "before", "in": "query" }, { "schema": { "type": "string", "enum": [ "pending", "succeeded", "failed" ] }, "required": false, "name": "status", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "has_more": { "type": "boolean" }, "next": { "type": [ "string", "null" ] } }, "required": [ "data", "has_more", "next" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited or over a limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "JavaScript", "label": "Node SDK", "source": "import { PadiMail } from \"@padimail/node\";\n\nconst pm = new PadiMail(process.env.PADIMAIL_API_KEY);\n\nconst result = await pm.webhooks.deliveries.list(\"wh_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S\", { status: \"failed\" });" }, { "lang": "Shell", "label": "cURL", "source": "curl 'https://api.padimail.app/v1/webhooks/wh_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S/deliveries?status=failed' \\\n -H \"Authorization: Bearer $PADIMAIL_API_KEY\"" }, { "lang": "Python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.get(\n \"https://api.padimail.app/v1/webhooks/wh_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S/deliveries\",\n headers={\"Authorization\": f\"Bearer {os.environ['PADIMAIL_API_KEY']}\"},\n params={ \"status\": \"failed\" },\n)\nresponse.raise_for_status()\nprint(response.json())" } ] } }, "/v1/webhooks/{id}/deliveries/{did}/retry": { "post": { "tags": [ "Webhooks" ], "summary": "Retry a delivery now", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "pattern": "^wh_[0-9A-Za-z]+$", "example": "wh_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S" }, "required": true, "name": "id", "in": "path" }, { "schema": { "type": "string", "pattern": "^whd_[0-9A-Za-z]+$", "example": "whd_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S" }, "required": true, "name": "did", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "delivery_id": { "type": "string", "pattern": "^whd_[0-9A-Za-z]+$", "example": "whd_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S" } }, "required": [ "delivery_id" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited or over a limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "JavaScript", "label": "Node SDK", "source": "import { PadiMail } from \"@padimail/node\";\n\nconst pm = new PadiMail(process.env.PADIMAIL_API_KEY);\n\nconst result = await pm.webhooks.deliveries.retry(\"wh_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S\", \"whd_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S\");" }, { "lang": "Shell", "label": "cURL", "source": "curl -X POST 'https://api.padimail.app/v1/webhooks/wh_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S/deliveries/whd_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S/retry' \\\n -H \"Authorization: Bearer $PADIMAIL_API_KEY\"" }, { "lang": "Python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.post(\n \"https://api.padimail.app/v1/webhooks/wh_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S/deliveries/whd_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S/retry\",\n headers={\"Authorization\": f\"Bearer {os.environ['PADIMAIL_API_KEY']}\"},\n)\nresponse.raise_for_status()\nprint(response.json())" } ] } }, "/v1/templates": { "post": { "tags": [ "Templates" ], "summary": "Create a template", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "maxLength": 255 }, "required": false, "name": "idempotency-key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "type": "string", "maxLength": 998 }, "html": { "type": "string" }, "text": { "type": "string" }, "variables": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$" }, "type": { "type": "string", "enum": [ "string", "number", "boolean", "object", "array" ], "default": "string" }, "required": { "type": "boolean", "default": false }, "sample": {} }, "required": [ "name" ] } }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "alias": { "type": "string", "pattern": "^[a-z0-9][a-z0-9_-]{0,63}$" }, "stream": { "type": "string", "enum": [ "transactional", "marketing" ] } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Template" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited or over a limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "JavaScript", "label": "Node SDK", "source": "import { PadiMail } from \"@padimail/node\";\n\nconst pm = new PadiMail(process.env.PADIMAIL_API_KEY);\n\nconst result = await pm.templates.create({\n name: \"Receipt\",\n alias: \"receipt\",\n subject: \"Your receipt #{{ order_no }}\",\n html: \"

Total: {{ total }}

\",\n variables: [\n { name: \"order_no\", required: true },\n { name: \"total\", required: true },\n ],\n});" }, { "lang": "Shell", "label": "cURL", "source": "curl -X POST 'https://api.padimail.app/v1/templates' \\\n -H \"Authorization: Bearer $PADIMAIL_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"Receipt\",\n \"alias\": \"receipt\",\n \"subject\": \"Your receipt #{{ order_no }}\",\n \"html\": \"

Total: {{ total }}

\",\n \"variables\": [\n { \"name\": \"order_no\", \"required\": true },\n { \"name\": \"total\", \"required\": true }\n ]\n}'" }, { "lang": "Python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.post(\n \"https://api.padimail.app/v1/templates\",\n headers={\"Authorization\": f\"Bearer {os.environ['PADIMAIL_API_KEY']}\"},\n json={\n \"name\": \"Receipt\",\n \"alias\": \"receipt\",\n \"subject\": \"Your receipt #{{ order_no }}\",\n \"html\": \"

Total: {{ total }}

\",\n \"variables\": [\n { \"name\": \"order_no\", \"required\": True },\n { \"name\": \"total\", \"required\": True },\n ],\n },\n)\nresponse.raise_for_status()\nprint(response.json())" } ] }, "get": { "tags": [ "Templates" ], "summary": "List templates", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "after", "in": "query" }, { "schema": { "type": "string" }, "required": false, "name": "before", "in": "query" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^tpl_[0-9A-Za-z]+$", "example": "tpl_01JBX7Q3F6ZK0Q9W1Y2R3T4V5S" }, "object": { "type": "string", "enum": [ "template" ] }, "name": { "type": "string" }, "alias": { "type": [ "string", "null" ] }, "stream": { "type": "string", "enum": [ "transactional", "marketing" ] }, "current_version": { "type": [ "integer", "null" ] }, "created_at": { "type": "string", "format": "date-time", "example": "2026-10-27T13:05:09Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2026-10-27T13:05:09Z" } }, "required": [ "id", "object", "name", "alias", "stream", "current_version", "created_at", "updated_at" ] } }, "has_more": { "type": "boolean" }, "next": { "type": [ "string", "null" ] } }, "required": [ "data", "has_more", "next" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited or over a limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "JavaScript", "label": "Node SDK", "source": "import { PadiMail } from \"@padimail/node\";\n\nconst pm = new PadiMail(process.env.PADIMAIL_API_KEY);\n\nconst result = await pm.templates.list();" }, { "lang": "Shell", "label": "cURL", "source": "curl 'https://api.padimail.app/v1/templates' \\\n -H \"Authorization: Bearer $PADIMAIL_API_KEY\"" }, { "lang": "Python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.get(\n \"https://api.padimail.app/v1/templates\",\n headers={\"Authorization\": f\"Bearer {os.environ['PADIMAIL_API_KEY']}\"},\n)\nresponse.raise_for_status()\nprint(response.json())" } ] } }, "/v1/templates/{id}": { "get": { "tags": [ "Templates" ], "summary": "Get a template", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "tpl_01JB… or receipt" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Template" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited or over a limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "JavaScript", "label": "Node SDK", "source": "import { PadiMail } from \"@padimail/node\";\n\nconst pm = new PadiMail(process.env.PADIMAIL_API_KEY);\n\nconst result = await pm.templates.get(\"receipt\");" }, { "lang": "Shell", "label": "cURL", "source": "curl 'https://api.padimail.app/v1/templates/receipt' \\\n -H \"Authorization: Bearer $PADIMAIL_API_KEY\"" }, { "lang": "Python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.get(\n \"https://api.padimail.app/v1/templates/receipt\",\n headers={\"Authorization\": f\"Bearer {os.environ['PADIMAIL_API_KEY']}\"},\n)\nresponse.raise_for_status()\nprint(response.json())" } ] }, "patch": { "tags": [ "Templates" ], "summary": "Update the draft", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "tpl_01JB… or receipt" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "type": "string", "maxLength": 998 }, "html": { "type": "string" }, "text": { "type": "string" }, "variables": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$" }, "type": { "type": "string", "enum": [ "string", "number", "boolean", "object", "array" ], "default": "string" }, "required": { "type": "boolean", "default": false }, "sample": {} }, "required": [ "name" ] } }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "alias": { "type": [ "string", "null" ], "pattern": "^[a-z0-9][a-z0-9_-]{0,63}$" }, "stream": { "type": "string", "enum": [ "transactional", "marketing" ] }, "restore_version": { "type": "integer" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Template" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited or over a limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "JavaScript", "label": "Node SDK", "source": "import { PadiMail } from \"@padimail/node\";\n\nconst pm = new PadiMail(process.env.PADIMAIL_API_KEY);\n\nconst result = await pm.templates.update(\"receipt\", { subject: \"Receipt for order #{{ order_no }}\" });" }, { "lang": "Shell", "label": "cURL", "source": "curl -X PATCH 'https://api.padimail.app/v1/templates/receipt' \\\n -H \"Authorization: Bearer $PADIMAIL_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{ \"subject\": \"Receipt for order #{{ order_no }}\" }'" }, { "lang": "Python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.patch(\n \"https://api.padimail.app/v1/templates/receipt\",\n headers={\"Authorization\": f\"Bearer {os.environ['PADIMAIL_API_KEY']}\"},\n json={ \"subject\": \"Receipt for order #{{ order_no }}\" },\n)\nresponse.raise_for_status()\nprint(response.json())" } ] }, "delete": { "tags": [ "Templates" ], "summary": "Delete a template", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "tpl_01JB… or receipt" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string" }, "deleted": { "type": "boolean", "enum": [ true ] } }, "required": [ "id", "object", "deleted" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited or over a limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "JavaScript", "label": "Node SDK", "source": "import { PadiMail } from \"@padimail/node\";\n\nconst pm = new PadiMail(process.env.PADIMAIL_API_KEY);\n\nconst result = await pm.templates.remove(\"receipt\");" }, { "lang": "Shell", "label": "cURL", "source": "curl -X DELETE 'https://api.padimail.app/v1/templates/receipt' \\\n -H \"Authorization: Bearer $PADIMAIL_API_KEY\"" }, { "lang": "Python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.delete(\n \"https://api.padimail.app/v1/templates/receipt\",\n headers={\"Authorization\": f\"Bearer {os.environ['PADIMAIL_API_KEY']}\"},\n)\nresponse.raise_for_status()\nprint(response.json())" } ] } }, "/v1/templates/{id}/publish": { "post": { "tags": [ "Templates" ], "summary": "Publish the draft as version N+1", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "tpl_01JB… or receipt" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Template" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited or over a limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "JavaScript", "label": "Node SDK", "source": "import { PadiMail } from \"@padimail/node\";\n\nconst pm = new PadiMail(process.env.PADIMAIL_API_KEY);\n\nconst result = await pm.templates.publish(\"receipt\");" }, { "lang": "Shell", "label": "cURL", "source": "curl -X POST 'https://api.padimail.app/v1/templates/receipt/publish' \\\n -H \"Authorization: Bearer $PADIMAIL_API_KEY\"" }, { "lang": "Python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.post(\n \"https://api.padimail.app/v1/templates/receipt/publish\",\n headers={\"Authorization\": f\"Bearer {os.environ['PADIMAIL_API_KEY']}\"},\n)\nresponse.raise_for_status()\nprint(response.json())" } ] } }, "/v1/templates/{id}/render": { "post": { "tags": [ "Templates" ], "summary": "Preview with variables", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "tpl_01JB… or receipt" }, "required": true, "name": "id", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "variables": { "type": "object", "additionalProperties": {} }, "version": { "type": "integer" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "type": [ "string", "null" ] }, "html": { "type": [ "string", "null" ] }, "text": { "type": [ "string", "null" ] }, "missing_variables": { "type": "array", "items": { "type": "string" } } }, "required": [ "subject", "html", "text", "missing_variables" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited or over a limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "JavaScript", "label": "Node SDK", "source": "import { PadiMail } from \"@padimail/node\";\n\nconst pm = new PadiMail(process.env.PADIMAIL_API_KEY);\n\nconst result = await pm.templates.render(\"receipt\", { variables: { order_no: \"1042\", total: \"₦12,500\" } });" }, { "lang": "Shell", "label": "cURL", "source": "curl -X POST 'https://api.padimail.app/v1/templates/receipt/render' \\\n -H \"Authorization: Bearer $PADIMAIL_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{ \"variables\": { \"order_no\": \"1042\", \"total\": \"₦12,500\" } }'" }, { "lang": "Python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.post(\n \"https://api.padimail.app/v1/templates/receipt/render\",\n headers={\"Authorization\": f\"Bearer {os.environ['PADIMAIL_API_KEY']}\"},\n json={ \"variables\": { \"order_no\": \"1042\", \"total\": \"₦12,500\" } },\n)\nresponse.raise_for_status()\nprint(response.json())" } ] } }, "/v1/templates/{id}/versions": { "get": { "tags": [ "Templates" ], "summary": "List a template's versions", "security": [ { "apiKey": [] } ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "example": "tpl_01JB… or receipt" }, "required": true, "name": "id", "in": "path" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateVersion" } } }, "required": [ "data" ] } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Permission error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limited or over a limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-codeSamples": [ { "lang": "JavaScript", "label": "Node SDK", "source": "import { PadiMail } from \"@padimail/node\";\n\nconst pm = new PadiMail(process.env.PADIMAIL_API_KEY);\n\nconst result = await pm.templates.versions(\"receipt\");" }, { "lang": "Shell", "label": "cURL", "source": "curl 'https://api.padimail.app/v1/templates/receipt/versions' \\\n -H \"Authorization: Bearer $PADIMAIL_API_KEY\"" }, { "lang": "Python", "label": "Python", "source": "import os\nimport requests\n\nresponse = requests.get(\n \"https://api.padimail.app/v1/templates/receipt/versions\",\n headers={\"Authorization\": f\"Bearer {os.environ['PADIMAIL_API_KEY']}\"},\n)\nresponse.raise_for_status()\nprint(response.json())" } ] } } }, "webhooks": {} }