openapi: 3.0.3 info: title: SentinMail API description: | Email campaign platform with drag-and-drop builder, subscriber management, and REST API. Bring Your Own SMTP — no per-email fees, no vendor lock-in. ## Authentication All API requests require an API key in the `X-API-Key` header. API keys are scoped to a single company and can be created from the Dashboard → Settings → API Keys. ## Base URL `https://api.sentinmail.app` version: 1.0.0 contact: name: SentinMail Support url: https://sentinmail.app license: name: Proprietary servers: - url: https://api.sentinmail.app description: Production security: - ApiKeyAuth: [] components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: "API key prefixed with `fm_`. Created from Dashboard → Settings → API Keys." schemas: PaginatedResponse: type: object properties: count: type: integer description: Total number of items next: type: string nullable: true description: URL for next page previous: type: string nullable: true description: URL for previous page results: type: array items: {} Campaign: type: object properties: id: type: string format: uuid name: type: string campaign_type: type: string enum: [to_list, to_receivers, custom] status: type: string enum: [pending, sending, completed, partial, failed, scheduled, cancelled] total_emails: type: integer sent_count: type: integer failed_count: type: integer scheduled_for: type: string format: date-time nullable: true created_at: type: string format: date-time updated_at: type: string format: date-time Subscriber: type: object properties: id: type: string format: uuid email: type: string format: email first_name: type: string last_name: type: string created_at: type: string format: date-time SubscriberList: type: object properties: id: type: string format: uuid name: type: string description: type: string subscriber_count: type: integer created_at: type: string format: date-time EmailTemplate: type: object properties: id: type: string format: uuid name: type: string subject: type: string body: type: string template_mode: type: string enum: [basic, visual] template_type: type: string enum: [marketing, transactional] created_at: type: string format: date-time updated_at: type: string format: date-time SmtpConfig: type: object properties: id: type: string format: uuid name: type: string host: type: string port: type: integer use_tls: type: boolean sender_name: type: string sender_email: type: string format: email created_at: type: string format: date-time WebhookEndpoint: type: object properties: id: type: string format: uuid url: type: string format: uri events: type: array items: type: string enum: [delivered, opened, clicked, bounced, unsubscribed] created_at: type: string format: date-time WebhookEvent: type: object properties: id: type: string format: uuid type: type: string enum: [delivered, opened, clicked, bounced, unsubscribed] recipient: type: string format: email sent_email_id: type: string format: uuid campaign_id: type: string format: uuid metadata: type: object timestamp: type: string format: date-time Suppression: type: object properties: id: type: string format: uuid email: type: string format: email domain: type: string reason: type: string created_at: type: string format: date-time Segment: type: object properties: id: type: string format: uuid name: type: string description: type: string rules: type: object properties: conditions: type: array items: type: object properties: field: type: string operator: type: string value: {} match: type: string enum: [all, any] created_at: type: string format: date-time Receiver: type: object required: [email] properties: email: type: string format: email description: Recipient email address cc: type: array items: type: string format: email description: Carbon copy recipients bcc: type: array items: type: string format: email description: Blind carbon copy recipients additionalProperties: type: string description: "Custom fields become [[variable]] template variables" Error: type: object properties: detail: type: string paths: # --- Sending Emails --- /api/emails/send/to-list/: post: tags: [Sending] summary: Send template to subscriber list description: Send a saved template to all subscribers in a list. Supports scheduling. requestBody: required: true content: application/json: schema: type: object required: [name, template_id, smtp_config_id, list_id] properties: name: type: string description: Campaign name maxLength: 255 template_id: type: string format: uuid smtp_config_id: type: string format: uuid list_id: type: string format: uuid scheduled_for: type: string format: date-time nullable: true description: "ISO-8601 datetime. null = send immediately." attachment_ids: type: array items: type: string format: uuid example: name: March Newsletter template_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 smtp_config_id: b2c3d4e5-f6a7-8901-bcde-f12345678901 list_id: c3d4e5f6-a7b8-9012-cdef-123456789012 responses: '201': description: Campaign created content: application/json: schema: $ref: '#/components/schemas/Campaign' '400': description: Validation error '401': description: Invalid API key '403': description: Plan limit or feature restriction /api/emails/send/to-receivers/: post: tags: [Sending] summary: Send template to specific receivers description: Send a saved template to specific recipients with per-recipient personalization variables. requestBody: required: true content: application/json: schema: type: object required: [name, template_id, smtp_config_id, receivers] properties: name: type: string maxLength: 255 template_id: type: string format: uuid smtp_config_id: type: string format: uuid receivers: type: array items: $ref: '#/components/schemas/Receiver' scheduled_for: type: string format: date-time nullable: true attachment_ids: type: array items: type: string format: uuid example: name: Renewal Reminder template_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 smtp_config_id: b2c3d4e5-f6a7-8901-bcde-f12345678901 receivers: - email: john@example.com first_name: John plan: Pro - email: jane@example.com first_name: Jane plan: Enterprise responses: '201': description: Campaign created content: application/json: schema: $ref: '#/components/schemas/Campaign' /api/emails/send/custom/: post: tags: [Sending] summary: Send custom email (no template needed) description: Send a custom email with inline subject and HTML body. Best for transactional emails. requestBody: required: true content: application/json: schema: type: object required: [name, smtp_config_id, subject, body, receivers] properties: name: type: string maxLength: 255 smtp_config_id: type: string format: uuid subject: type: string description: "Subject line. Supports [[variable]] syntax." body: type: string description: "HTML body. Supports [[variable]] syntax." receivers: type: array items: $ref: '#/components/schemas/Receiver' attachment_ids: type: array items: type: string format: uuid example: name: Order Confirmation smtp_config_id: b2c3d4e5-f6a7-8901-bcde-f12345678901 subject: "Order #[[order_id]] confirmed, [[first_name]]!" body: "

Thanks, [[first_name]]!

Order #[[order_id]] confirmed.

" receivers: - email: john@example.com first_name: John order_id: "12345" total: "79.99" responses: '201': description: Campaign created content: application/json: schema: $ref: '#/components/schemas/Campaign' # --- Subscribers --- /api/emails/subscribers/: get: tags: [Subscribers] summary: List subscribers parameters: - name: search in: query schema: type: string description: Search by name or email - name: ordering in: query schema: type: string description: "Sort field (e.g. -created_at)" - name: page in: query schema: type: integer responses: '200': description: Paginated list of subscribers content: application/json: schema: allOf: - $ref: '#/components/schemas/PaginatedResponse' - type: object properties: results: type: array items: $ref: '#/components/schemas/Subscriber' post: tags: [Subscribers] summary: Add a subscriber requestBody: required: true content: application/json: schema: type: object required: [email] properties: email: type: string format: email first_name: type: string last_name: type: string example: email: newuser@example.com first_name: Jane last_name: Doe responses: '201': description: Subscriber created content: application/json: schema: $ref: '#/components/schemas/Subscriber' /api/emails/subscribers/{id}/: parameters: - name: id in: path required: true schema: type: string format: uuid get: tags: [Subscribers] summary: Get subscriber responses: '200': description: Subscriber details content: application/json: schema: $ref: '#/components/schemas/Subscriber' patch: tags: [Subscribers] summary: Update subscriber requestBody: content: application/json: schema: type: object properties: first_name: type: string last_name: type: string responses: '200': description: Updated subscriber delete: tags: [Subscribers] summary: Delete subscriber responses: '204': description: Deleted /api/emails/subscribers/bulk/: post: tags: [Subscribers] summary: Bulk import subscribers (CSV) requestBody: required: true content: multipart/form-data: schema: type: object properties: file: type: string format: binary description: "CSV file with columns: email, first_name, last_name" responses: '201': description: Import results /api/emails/subscribers/bulk-delete/: post: tags: [Subscribers] summary: Bulk delete subscribers requestBody: required: true content: application/json: schema: type: object required: [subscriber_ids] properties: subscriber_ids: type: array items: type: string format: uuid responses: '200': description: Deletion results /api/emails/subscribers/bulk-update-lists/: post: tags: [Subscribers] summary: Add/remove subscribers from lists requestBody: required: true content: application/json: schema: type: object required: [subscriber_ids] properties: subscriber_ids: type: array items: type: string format: uuid add_to_lists: type: array items: type: string format: uuid remove_from_lists: type: array items: type: string format: uuid responses: '200': description: Update results /api/emails/subscribers/export/: get: tags: [Subscribers] summary: Export subscribers as CSV responses: '200': description: CSV file download content: text/csv: {} # --- Lists --- /api/emails/lists/: get: tags: [Lists] summary: List all subscriber lists responses: '200': description: Paginated list content: application/json: schema: allOf: - $ref: '#/components/schemas/PaginatedResponse' - type: object properties: results: type: array items: $ref: '#/components/schemas/SubscriberList' post: tags: [Lists] summary: Create a subscriber list requestBody: required: true content: application/json: schema: type: object required: [name] properties: name: type: string description: type: string example: name: Weekly Newsletter description: Subscribers to the weekly product update responses: '201': description: List created content: application/json: schema: $ref: '#/components/schemas/SubscriberList' /api/emails/lists/{id}/: parameters: - name: id in: path required: true schema: type: string format: uuid get: tags: [Lists] summary: Get list responses: '200': description: List details patch: tags: [Lists] summary: Update list requestBody: content: application/json: schema: type: object properties: name: type: string description: type: string responses: '200': description: Updated list delete: tags: [Lists] summary: Delete list responses: '204': description: Deleted # --- Templates --- /api/emails/templates/: get: tags: [Templates] summary: List email templates responses: '200': description: Paginated list of templates post: tags: [Templates] summary: Create email template requestBody: required: true content: application/json: schema: type: object required: [name, subject] properties: name: type: string subject: type: string body: type: string template_mode: type: string enum: [basic, visual] template_type: type: string enum: [marketing, transactional] example: name: Welcome Email subject: "Welcome, [[first_name]]!" body: "

Welcome!

Thanks for joining, [[first_name]].

" template_mode: basic template_type: marketing responses: '201': description: Template created content: application/json: schema: $ref: '#/components/schemas/EmailTemplate' /api/emails/templates/{id}/: parameters: - name: id in: path required: true schema: type: string format: uuid get: tags: [Templates] summary: Get template responses: '200': description: Template details patch: tags: [Templates] summary: Update template responses: '200': description: Updated template delete: tags: [Templates] summary: Delete template responses: '204': description: Deleted # --- SMTP Configs --- /api/emails/smtp-configs/: get: tags: [SMTP] summary: List SMTP configurations responses: '200': description: Paginated list post: tags: [SMTP] summary: Create SMTP configuration requestBody: required: true content: application/json: schema: type: object required: [name, host, port, username, password, sender_email] properties: name: type: string host: type: string port: type: integer username: type: string password: type: string use_tls: type: boolean default: true sender_name: type: string sender_email: type: string format: email example: name: Production SES host: email-smtp.us-east-1.amazonaws.com port: 587 username: AKIAIOSFODNN7EXAMPLE password: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY use_tls: true sender_name: My App sender_email: hello@myapp.com responses: '201': description: SMTP config created /api/emails/smtp-configs/{id}/: parameters: - name: id in: path required: true schema: type: string format: uuid get: tags: [SMTP] summary: Get SMTP config responses: '200': description: Config details patch: tags: [SMTP] summary: Update SMTP config responses: '200': description: Updated delete: tags: [SMTP] summary: Delete SMTP config responses: '204': description: Deleted /api/emails/smtp/validate/: post: tags: [SMTP] summary: Validate SMTP credentials description: Test an SMTP connection without saving the configuration. requestBody: required: true content: application/json: schema: type: object required: [host, port, username, password] properties: host: type: string port: type: integer username: type: string password: type: string use_tls: type: boolean responses: '200': description: Validation result # --- Campaigns --- /api/emails/campaigns/: get: tags: [Campaigns] summary: List campaigns responses: '200': description: Paginated list of campaigns /api/emails/campaigns/{id}/: parameters: - name: id in: path required: true schema: type: string format: uuid get: tags: [Campaigns] summary: Get campaign status responses: '200': description: Campaign details content: application/json: schema: $ref: '#/components/schemas/Campaign' /api/emails/campaigns/{id}/resume/: parameters: - name: id in: path required: true schema: type: string format: uuid post: tags: [Campaigns] summary: Resume failed campaign description: Resume a campaign with status partial or failed. Already-sent recipients are skipped. responses: '200': description: Campaign resumed /api/emails/campaigns/{id}/cancel/: parameters: - name: id in: path required: true schema: type: string format: uuid post: tags: [Campaigns] summary: Cancel scheduled campaign description: Cancel a campaign with status scheduled. responses: '200': description: Campaign cancelled /api/emails/campaigns/{id}/analytics/: parameters: - name: id in: path required: true schema: type: string format: uuid get: tags: [Campaigns] summary: Get campaign analytics responses: '200': description: Analytics data /api/emails/campaigns/{id}/export/: parameters: - name: id in: path required: true schema: type: string format: uuid get: tags: [Campaigns] summary: Export campaign results as CSV responses: '200': description: CSV download # --- Webhooks --- /api/emails/webhook-endpoints/: get: tags: [Webhooks] summary: List webhook endpoints responses: '200': description: Paginated list post: tags: [Webhooks] summary: Register webhook endpoint requestBody: required: true content: application/json: schema: type: object required: [url, events] properties: url: type: string format: uri description: HTTPS endpoint URL events: type: array items: type: string enum: [delivered, opened, clicked, bounced, unsubscribed] example: url: https://yourapp.com/webhooks/sentinmail events: [delivered, opened, clicked, bounced, unsubscribed] responses: '201': description: Webhook created content: application/json: schema: $ref: '#/components/schemas/WebhookEndpoint' /api/emails/webhook-endpoints/{id}/: parameters: - name: id in: path required: true schema: type: string format: uuid get: tags: [Webhooks] summary: Get webhook responses: '200': description: Webhook details put: tags: [Webhooks] summary: Update webhook requestBody: content: application/json: schema: type: object properties: url: type: string format: uri events: type: array items: type: string responses: '200': description: Updated delete: tags: [Webhooks] summary: Delete webhook responses: '204': description: Deleted # --- Suppressions --- /api/emails/suppressions/: get: tags: [Suppressions] summary: List suppressions responses: '200': description: Paginated list post: tags: [Suppressions] summary: Add suppression requestBody: required: true content: application/json: schema: type: object properties: email: type: string format: email domain: type: string reason: type: string example: email: bounced@example.com reason: Hard bounce responses: '201': description: Suppression created /api/emails/suppressions/{id}/: parameters: - name: id in: path required: true schema: type: string format: uuid get: tags: [Suppressions] summary: Get suppression responses: '200': description: Suppression details delete: tags: [Suppressions] summary: Delete suppression responses: '204': description: Deleted # --- Segments --- /api/emails/segments/: get: tags: [Segments] summary: List segments responses: '200': description: Paginated list post: tags: [Segments] summary: Create segment requestBody: required: true content: application/json: schema: type: object required: [name, rules] properties: name: type: string description: type: string rules: type: object properties: conditions: type: array items: type: object properties: field: type: string operator: type: string value: {} match: type: string enum: [all, any] example: name: Engaged Users description: Opened an email in the last 30 days rules: conditions: - field: last_opened operator: within_days value: 30 match: all responses: '201': description: Segment created /api/emails/segments/{id}/: parameters: - name: id in: path required: true schema: type: string format: uuid get: tags: [Segments] summary: Get segment responses: '200': description: Segment details patch: tags: [Segments] summary: Update segment responses: '200': description: Updated delete: tags: [Segments] summary: Delete segment responses: '204': description: Deleted # --- Media --- /api/emails/media/: get: tags: [Media] summary: List media files responses: '200': description: Paginated list post: tags: [Media] summary: Upload media file requestBody: required: true content: multipart/form-data: schema: type: object properties: file: type: string format: binary responses: '201': description: File uploaded /api/emails/media/{id}/: parameters: - name: id in: path required: true schema: type: string format: uuid get: tags: [Media] summary: Get media file responses: '200': description: File details delete: tags: [Media] summary: Delete media file responses: '204': description: Deleted # --- Sent Emails & Events --- /api/emails/sent-emails/: get: tags: [Tracking] summary: List sent emails description: Read-only list of all sent emails with delivery status. responses: '200': description: Paginated list /api/emails/events/: get: tags: [Tracking] summary: List email events description: Open, click, bounce, and unsubscribe events. responses: '200': description: Paginated list # --- Public (No Auth) --- /api/emails/public/subscribe/{company_id}/: parameters: - name: company_id in: path required: true schema: type: string format: uuid post: tags: [Public] summary: Subscribe to newsletter description: Public endpoint for visitor signups. Rate limited to 3/min per IP. security: [] requestBody: content: application/json: schema: type: object required: [email] properties: email: type: string format: email first_name: type: string responses: '201': description: Subscribed /api/emails/public/unsubscribe/{sent_email_id}/: parameters: - name: sent_email_id in: path required: true schema: type: string format: uuid get: tags: [Public] summary: View unsubscribe page security: [] responses: '200': description: Unsubscribe page post: tags: [Public] summary: Process unsubscribe security: [] responses: '200': description: Unsubscribed /api/emails/public/view/{sent_email_id}/: parameters: - name: sent_email_id in: path required: true schema: type: string format: uuid get: tags: [Public] summary: View email in browser security: [] responses: '200': description: Email content /api/emails/public/confirm/{token}/: parameters: - name: token in: path required: true schema: type: string post: tags: [Public] summary: Confirm double opt-in subscription security: [] responses: '200': description: Subscription confirmed /api/emails/public/preferences/{token}/: parameters: - name: token in: path required: true schema: type: string get: tags: [Public] summary: View subscriber preferences security: [] responses: '200': description: Preferences page put: tags: [Public] summary: Update subscriber preferences security: [] responses: '200': description: Preferences updated tags: - name: Sending description: Send emails via three methods - name: Subscribers description: Manage email subscribers - name: Lists description: Organize subscribers into lists - name: Templates description: Create and manage email templates - name: SMTP description: SMTP server configurations - name: Campaigns description: Monitor and manage campaigns - name: Webhooks description: Real-time delivery event notifications - name: Suppressions description: Block emails to specific addresses - name: Segments description: Dynamic subscriber groups - name: Media description: File uploads and attachments - name: Tracking description: Sent emails and delivery events - name: Public description: No-auth endpoints for subscribers