{ "openapi": "3.1.0", "info": { "title": "SalesBlink API", "version": "1.0.0", "description": "SalesBlink Public API Documentation\n\n## Get Your API Key\n\nGet your API Key here: https://run.salesblink.io/account/integration/api\n\n## Authentication\n\nAll API endpoints require an API Key passed in the `Authorization` header:\n```\nAuthorization: your_salesblink_api_key\n```\n\n## Base URL\n- `https://run.salesblink.io/api/public/v1.0.0`\n\n## Rate Limits\n\nThe SalesBlink API implements tiered rate limiting based on request type:\n\n| Tier | Limit | Applies To |\n|------|-------|------------|\n| **General** | 30 requests per minute | GET requests |\n| **Sensitive** | 15 requests per minute | POST and PATCH requests |\n| **Restricted** | 10 requests per minute | PUT and DELETE requests |\n\n### Requesting Rate Limit Increases\n\nNeed higher limits? Contact us at https://salesblink.io/contact-us to discuss your requirements.\n\n## Support\nFor support, contact: https://salesblink.io/contact-us", "contact": { "name": "SalesBlink Support", "url": "https://salesblink.io/contact-us" } }, "servers": [ { "url": "https://run.salesblink.io/api/public/v1.0.0", "description": "Production API Server" }, { "url": "http://localhost:3000/api/public/v1.0.0", "description": "Local Development Server" } ], "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "Authorization: your_salesblink_key" } }, "schemas": { "SuccessResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Operation completed successfully" } } }, "ErrorResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Error description" } } }, "Contact": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique contact ID" }, "Email": { "type": "string", "format": "email" }, "First_Name": { "type": "string" }, "Last_Name": { "type": "string" }, "Phone": { "type": "string" }, "list_id": { "type": "string" }, "owned_by": { "type": "string", "description": "Email of the owner" }, "archived": { "type": "boolean" }, "accuracy": { "type": "string", "description": "Email verification accuracy score" } } }, "Step": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "email", "delay" ], "description": "Type of step - email or delay" }, "template_id": { "type": "string", "description": "Required for email type - the template UUID" }, "days": { "type": "integer", "description": "Required for delay type - number of days to wait" } }, "example": { "type": "email", "template_id": "template_id_1" } }, "EmailSendingHours": { "type": "object", "properties": { "name": { "type": "string", "description": "Day of the week (Monday, Tuesday, etc.)" }, "enabled": { "type": "boolean", "description": "Whether sending is enabled on this day" }, "fromTime": { "type": "string", "pattern": "^([01]?[0-9]|2[0-3]):[0-5][0-9]$", "description": "Start time in 24-hour format (HH:MM)" }, "toTime": { "type": "string", "pattern": "^([01]?[0-9]|2[0-3]):[0-5][0-9]$", "description": "End time in 24-hour format (HH:MM)" } } } } }, "paths": { "/signup": { "post": { "summary": "Signup for SalesBlink", "operationId": "signup", "tags": [ "Authentication" ], "description": "Create a new SalesBlink account. This endpoint is public and does not require an API key.\nRate limited to 5 per day per IP. Successful signup returns an API key for immediate use.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "password", "name" ], "properties": { "email": { "type": "string", "format": "email", "example": "user@example.com" }, "password": { "type": "string", "minLength": 8, "maxLength": 48, "description": "Password must be 8-48 chars and contain at least one uppercase and one lowercase letter.", "example": "SecurePassword123" }, "name": { "type": "string", "example": "John Doe" } } } } } }, "responses": { "200": { "description": "Account created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "account_id": { "type": "string" }, "user_id": { "type": "string" }, "api_key": { "type": "string" } } } } } } } } } } }, "/lists": { "get": { "summary": "Get All Lists", "operationId": "get_all_lists", "tags": [ "Lists" ], "description": "Retrieve all lead lists in your workspace. \nFor AI agents: Use search parameter to filter by name, use archived=true to see archived lists.\n", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 500, "maximum": 100 }, "description": "Maximum number of lists to return (max 100 for v1.0.0)" }, { "in": "query", "name": "skip", "schema": { "type": "integer", "default": 0 }, "description": "Number of lists to skip for pagination" }, { "in": "query", "name": "search", "schema": { "type": "string" }, "description": "Search query to filter lists by name (case-insensitive)" }, { "in": "query", "name": "starred", "schema": { "type": "boolean" }, "description": "Filter by starred status" }, { "in": "query", "name": "archived", "schema": { "type": "boolean" }, "description": "Filter by archived status" }, { "in": "query", "name": "owned_by", "schema": { "type": "string" }, "description": "Filter by owner user ID (admin/owner only)" } ], "responses": { "200": { "description": "A list of lead lists with owner information", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "contacts_count": { "type": "integer" }, "starred": { "type": "boolean" }, "archived": { "type": "boolean" }, "owned_by": { "type": "string", "description": "Email of the list owner" }, "last_modified": { "type": "string", "format": "date-time" } } } } } } } } } } }, "post": { "summary": "Create a List", "operationId": "create_list", "tags": [ "Lists" ], "description": "Create a new lead list to organize contacts. \nFor AI agents: Consider enabling verification for better deliverability. Set removeDuplicates to maintain list quality.\n", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "example": "My New List", "description": "Name of the list (required)" }, "folder": { "type": "string", "example": "optional_folder_id", "description": "Optional folder ID to organize the list" }, "starred": { "type": "boolean", "example": false, "description": "Whether to star the list" }, "verification": { "type": "boolean", "example": false, "description": "Enable email verification for contacts in this list (can only be enabled, not disabled later)" }, "archive_invalid": { "type": "boolean", "example": false, "description": "Archive contacts with invalid emails after verification" }, "archive_risky": { "type": "boolean", "example": false, "description": "Archive contacts with risky emails after verification" }, "removeDuplicates": { "type": "object", "properties": { "inThisList": { "type": "boolean", "example": false, "description": "Remove duplicate emails within this list" }, "inOtherLists": { "type": "boolean", "example": false, "description": "Remove contacts that exist in other lists" }, "inTeamMembersLists": { "type": "boolean", "example": false, "description": "Remove contacts that exist in team members lists" } } } } } } } }, "responses": { "200": { "description": "List created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "contacts_count": { "type": "integer" }, "date_created": { "type": "string", "format": "date-time" } } } } } } } } } } }, "/lists/{id}": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The unique identifier of the list" } ], "get": { "summary": "Get a Specific List", "operationId": "get_list", "tags": [ "Lists" ], "description": "Retrieve detailed information about a specific lead list.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "List details with owner information", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "contacts_count": { "type": "integer" }, "starred": { "type": "boolean" }, "archived": { "type": "boolean" }, "owned_by": { "type": "string", "description": "Email of the list owner" }, "last_modified": { "type": "string", "format": "date-time" } } } } } } } } } }, "patch": { "summary": "Update a List", "operationId": "update_list", "tags": [ "Lists" ], "description": "Update list properties. For AI agents: Note that verification settings can only be turned ON, not OFF once enabled.\nUse PUT /lists/{id}/archive to archive/unarchive lists instead of this endpoint.\n", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "New name for the list" }, "starred": { "type": "boolean", "description": "Star or unstar the list" }, "duplicate_removal": { "type": "boolean", "description": "Remove duplicate contacts from this list" }, "duplicate_removal_other_list": { "type": "boolean", "description": "Remove contacts that exist in other lists" }, "duplicate_removal_team_list": { "type": "boolean", "description": "Remove contacts that exist in team members lists" }, "verification": { "type": "boolean", "description": "Enable email verification (can only be turned ON, not OFF)" }, "archive_invalid": { "type": "boolean", "description": "Archive invalid emails (can only be turned ON, not OFF)" }, "archive_risky": { "type": "boolean", "description": "Archive risky emails (can only be turned ON, not OFF)" } } } } } }, "responses": { "200": { "description": "List updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } } } } }, "/lists/{id}/archive": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The unique identifier of the list" } ], "put": { "summary": "Archive or Unarchive a List", "operationId": "archive_list", "tags": [ "Lists" ], "description": "Archive or unarchive a list. Archiving removes the list from active views but preserves all data.\nFor AI agents: When archiving, the list is automatically paused if active.\n", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "archived": { "type": "boolean", "default": true, "description": "true to archive, false to unarchive" } } } } } }, "responses": { "200": { "description": "List archived/unarchived successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } } } } }, "/lists/{id}/leads": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The unique identifier of the list" } ], "get": { "summary": "Get Leads in a List", "operationId": "get_leads", "tags": [ "Leads" ], "description": "Retrieve all leads (contacts) in a specific list with pagination.\nFor AI agents: Use limit parameter (max 100) and skip for pagination.\n", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 100, "maximum": 100 }, "description": "Maximum number of leads to return (max 100)" }, { "in": "query", "name": "skip", "schema": { "type": "integer", "default": 0 }, "description": "Number of leads to skip for pagination" }, { "in": "query", "name": "owned_by", "schema": { "type": "string" }, "description": "Filter by owner (admin/owner only)" } ], "responses": { "200": { "description": "List of leads with pagination info", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } }, "total": { "type": "integer", "description": "Total number of contacts in the list" } } } } } } } } } } }, "/templates": { "get": { "summary": "Get All Templates", "operationId": "get_all_templates", "tags": [ "Templates" ], "description": "Retrieve all email templates in your workspace.\nFor AI agents: Each template includes a cold_email_score field indicating the quality of the template content.\n", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 10, "maximum": 100 }, "description": "Maximum number of templates to return" }, { "in": "query", "name": "skip", "schema": { "type": "integer", "default": 0 }, "description": "Number of templates to skip for pagination" }, { "in": "query", "name": "search", "schema": { "type": "string" }, "description": "Search query to filter templates by name" }, { "in": "query", "name": "starred", "schema": { "type": "boolean" }, "description": "Filter by starred status" }, { "in": "query", "name": "archived", "schema": { "type": "boolean" }, "description": "Filter by archived status" }, { "in": "query", "name": "owned_by", "schema": { "type": "string" }, "description": "Filter by owner ID (admin/owner only)" } ], "responses": { "200": { "description": "A collection of email templates with cold email scores", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "subject_line": { "type": "string" }, "starred": { "type": "boolean" }, "archived": { "type": "boolean" }, "cold_email_score": { "type": "object", "description": "Computed score indicating template quality", "properties": { "score": { "type": "number" }, "rating": { "type": "string", "enum": [ "Perfect", "Good", "Poor", "Very Poor" ] } } }, "owned_by": { "type": "string", "description": "Email of the template owner" }, "date_created": { "type": "string", "format": "date-time" } } } } } } } } } } }, "post": { "summary": "Create a Template", "operationId": "create_template", "tags": [ "Templates" ], "description": "Create a new email template for use in sequences.\nFor AI agents: The template will be scored automatically. Use personalization variables like {{first_name}}, {{company}}, etc.\nMaximum 3 attachments allowed.\n", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "subject_line", "content" ], "properties": { "name": { "type": "string", "example": "Cold Outreach 1", "description": "Name of the template" }, "subject_line": { "type": "string", "example": "Quick Question", "description": "Email subject line" }, "content": { "type": "string", "example": "

Hi {{first_name}}...

", "description": "HTML content of the email. Use {{variable}} syntax for personalization" }, "folder": { "type": "string", "example": "optional_folder_id", "description": "Optional folder ID" }, "starred": { "type": "boolean", "example": false, "description": "Whether to star the template" }, "attachments": { "type": "array", "description": "Array of files to attach (max 3 files)", "items": { "type": "string", "format": "binary" } } } } } } }, "responses": { "200": { "description": "Template created successfully with cold email score", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "cold_email_score": { "type": "object", "properties": { "score": { "type": "number" }, "rating": { "type": "string" } } }, "date_created": { "type": "string", "format": "date-time" } } } } } } } } } } }, "/templates/{id}": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The unique identifier of the template" } ], "get": { "summary": "Get a Specific Template", "operationId": "get_template", "tags": [ "Templates" ], "description": "Retrieve complete details of a specific email template including cold email score.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Template details with content and score", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "subject_line": { "type": "string" }, "content": { "type": "string" }, "starred": { "type": "boolean" }, "archived": { "type": "boolean" }, "cold_email_score": { "type": "object", "properties": { "score": { "type": "number" }, "rating": { "type": "string" }, "details": { "type": "object", "properties": { "word_count": { "type": "integer" }, "personalization_count": { "type": "integer" }, "link_count": { "type": "integer" }, "image_count": { "type": "integer" }, "question_count": { "type": "integer" }, "spam_word_count": { "type": "integer" } } } } } } } } } } } } } }, "patch": { "summary": "Update a Template", "operationId": "update_template", "tags": [ "Templates" ], "description": "Update an existing email template. \nFor AI agents: Existing attachments cannot be removed via attachment field - use remove_attachments array instead.\n", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "New name for the template" }, "subject_line": { "type": "string", "description": "New subject line" }, "content": { "type": "string", "description": "New HTML content" }, "starred": { "type": "boolean", "description": "Star or unstar the template" }, "attachments": { "type": "array", "description": "Array of new files to append (max 3 total)", "items": { "type": "string", "format": "binary" } }, "remove_attachments": { "type": "array", "description": "Array of existing attachment names to remove", "items": { "type": "string" }, "example": [ "attachment1.jpg", "attachment2.pdf" ] } } } } } }, "responses": { "200": { "description": "Template updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } } } } }, "/templates/{id}/archive": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The unique identifier of the template" } ], "put": { "summary": "Archive or Unarchive a Template", "operationId": "archive_template", "tags": [ "Templates" ], "description": "Archive or unarchive an email template.", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "archived": { "type": "boolean", "default": true, "description": "true to archive, false to unarchive" } } } } } }, "responses": { "200": { "description": "Template archived/unarchived successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } } } } }, "/inbox": { "get": { "summary": "Get Inbox Threads", "operationId": "get_inbox_threads", "tags": [ "Inbox" ], "description": "Retrieve email threads from your unified inbox.\nFor AI agents: Use type=replies to get only replies from leads, type=sent for sent emails.\n", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "query", "name": "type", "schema": { "type": "string", "enum": [ "all", "replies", "sent" ], "default": "replies" }, "description": "Type of threads to retrieve" }, { "in": "query", "name": "sequence", "description": "Filter by sequence id", "schema": { "type": "string" } }, { "in": "query", "name": "search", "schema": { "type": "string" }, "description": "Search query for thread content" }, { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 10, "maximum": 100 }, "description": "Maximum number of threads to return" }, { "in": "query", "name": "skip", "schema": { "type": "integer", "default": 0 }, "description": "Number of threads to skip for pagination" }, { "in": "query", "name": "days", "description": "Fetch inbox items from the last X days", "schema": { "type": "integer" } }, { "in": "query", "name": "outcome", "schema": { "type": "string" }, "description": "Filter by outcome classification" }, { "in": "query", "name": "unread", "schema": { "type": "boolean" }, "description": "Filter by unread status" }, { "in": "query", "name": "sender", "schema": { "type": "string" }, "description": "Filter by sender email" }, { "in": "query", "name": "starred", "schema": { "type": "boolean" }, "description": "Filter by starred status" }, { "in": "query", "name": "archived", "schema": { "type": "boolean" }, "description": "Filter by archived status" }, { "in": "query", "name": "owned_by", "schema": { "type": "string" }, "description": "Filter by owner (admin/owner only)" } ], "responses": { "200": { "description": "Thread tasks response with total count and results", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "totalCount": { "type": "integer", "description": "Total number of matching threads" }, "result": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "messageId": { "type": "string" }, "task_type": { "type": "string", "example": "reply" }, "email": { "type": "string" }, "data": { "type": "object", "properties": { "email": { "type": "object", "properties": { "subject": { "type": "string" }, "body": { "type": "string" } } } } }, "scheduled_time": { "type": "integer" }, "unread": { "type": "boolean" }, "sender": { "type": "string" } } } } } } } } } } } } } }, "/inbox/{messageId}/thread": { "parameters": [ { "in": "path", "name": "messageId", "required": true, "schema": { "type": "string" }, "description": "The unique message ID of the thread" } ], "get": { "summary": "Get Thread Messages", "operationId": "get_thread_messages", "tags": [ "Inbox" ], "description": "Retrieve all emails associated with a specific message thread.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "All tasks/emails in the conversation thread", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "task_type": { "type": "string" }, "data": { "type": "object" }, "scheduled_time": { "type": "integer" } } } } } } } } } } } }, "/inbox/{messageId}/reply": { "parameters": [ { "in": "path", "name": "messageId", "required": true, "schema": { "type": "string" }, "description": "The unique message ID to reply to" } ], "post": { "summary": "Send a Reply", "operationId": "send_reply", "tags": [ "Inbox" ], "description": "Send a reply to a lead's email. The reply will be sent from the same sender that originally contacted the lead.\nFor AI agents: This maintains conversation continuity automatically.\n", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "content" ], "properties": { "content": { "type": "string", "example": "

Thanks for getting back to me!

", "description": "HTML content of the reply" }, "cc": { "type": "string", "example": "optional@cc.com", "description": "Optional CC email address" }, "bcc": { "type": "string", "example": "", "description": "Optional BCC email address" } } } } } }, "responses": { "200": { "description": "Reply scheduled successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "task_type": { "type": "string", "example": "reply" }, "status": { "type": "string", "example": "scheduled" } } } } } } } } } } }, "/inbox/{messageId}": { "parameters": [ { "in": "path", "name": "messageId", "required": true, "schema": { "type": "string" }, "description": "The unique message ID" } ], "patch": { "summary": "Update Mail State", "operationId": "update_mail_state", "tags": [ "Inbox" ], "description": "Update the state of an inbox item. Mark emails as read/unread and set conversation outcomes.\nFor AI agents: Use outcome field to classify replies as \"positive\", \"negative\", etc.\n", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "unread": { "type": "boolean", "example": false, "description": "Mark as read (false) or unread (true)" }, "outcome": { "type": "string", "example": "positive", "description": "Set conversation outcome (e.g., positive, negative, neutral)" } } } } } }, "responses": { "200": { "description": "Mail state updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } } } } }, "/sequences": { "get": { "summary": "Get All Sequences", "operationId": "get_all_sequences", "tags": [ "Sequences" ], "description": "Retrieve all email sequences in your workspace.\nFor AI agents: Use status filter to find active, paused, or completed sequences.\n", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 1000, "maximum": 100 }, "description": "Maximum number of sequences to return (max 100)" }, { "in": "query", "name": "skip", "schema": { "type": "integer", "default": 0 }, "description": "Number of sequences to skip for pagination" }, { "in": "query", "name": "search", "schema": { "type": "string" }, "description": "Search query to filter sequences by name" }, { "in": "query", "name": "starred", "schema": { "type": "boolean" }, "description": "Filter by starred status" }, { "in": "query", "name": "archived", "schema": { "type": "boolean" }, "description": "Filter by archived status" }, { "in": "query", "name": "owned_by", "schema": { "type": "string" }, "description": "Filter by owner (admin/owner only)" }, { "in": "query", "name": "status", "description": "Filter sequences by status", "schema": { "type": "string", "enum": [ "active", "paused", "completed", "all" ] } } ], "responses": { "200": { "description": "A collection of sequences", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "paused": { "type": "boolean" }, "starred": { "type": "boolean" }, "archived": { "type": "boolean" }, "owned_by": { "type": "string", "description": "Email of the sequence owner" }, "sent": { "type": "integer" }, "opens": { "type": "integer" }, "clicks": { "type": "integer" }, "replies": { "type": "integer" } } } } } } } } } } }, "post": { "summary": "Create a Sequence", "operationId": "create_sequence", "tags": [ "Sequences" ], "description": "Create a new automated email sequence.\nFor AI agents: \n- Steps array defines the sequence flow with email and delay nodes\n- Each email step requires a template_id\n- Each delay step requires days (number of days to wait)\n- If launchTimingMode is not provided or 'now', sequence starts 5 minutes from now\n- If 'schedule', provide scheduledAt as a future UTC timestamp (milliseconds) OR an ISO 8601 datetime with timezone offset (e.g. '2026-07-08T16:30:00+05:30' for 4:30 PM IST)\n- When scheduling, always provide the user's timezone in the timezone field (e.g. 'Asia/Calcutta') so the sequence does not default to America/New_York\n", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "senders", "lists", "steps" ], "properties": { "name": { "type": "string", "example": "Outbound Campaign V1", "description": "Name of the sequence (required)" }, "folder": { "type": "string", "example": "optional_folder_id", "description": "Optional folder ID" }, "starred": { "type": "boolean", "example": false, "description": "Whether to star the sequence" }, "senders": { "type": "string", "description": "Comma-separated sender/folder UUIDs. Can include both sender IDs and folder IDs", "example": "uuid1,uuid2,folder_uuid1" }, "lists": { "type": "array", "items": { "type": "string" }, "example": [ "list_uuid1" ], "description": "Array of list UUIDs to include (required)" }, "steps": { "type": "array", "description": "Ordered array of sequence steps (required). Mix of email and delay steps", "items": { "$ref": "#/components/schemas/Step" }, "example": [ { "type": "email", "template_id": "template_id_1" }, { "type": "delay", "days": 3 }, { "type": "email", "template_id": "template_id_2" } ] }, "launchTimingMode": { "type": "string", "enum": [ "now", "schedule" ], "example": "now", "description": "When to launch: 'now' (default, starts in 5 mins) or 'schedule' (requires scheduledAt and timezone)" }, "scheduledAt": { "oneOf": [ { "type": "integer", "description": "UTC Timestamp in milliseconds", "example": 1699999999999 }, { "type": "string", "format": "date-time", "description": "ISO 8601 datetime with timezone offset", "example": "2026-07-08T16:30:00+05:30" } ], "description": "Launch time (required if launchTimingMode=schedule, must be future). UTC milliseconds OR ISO 8601 datetime with timezone offset." }, "timezone": { "type": "string", "example": "Asia/Calcutta", "description": "IANA timezone for scheduled sending (e.g. 'Asia/Calcutta', 'America/New_York'). Required when launchTimingMode=schedule to avoid defaulting to America/New_York." }, "paused": { "type": "boolean", "example": true, "description": "Whether to create the sequence in paused state (default true)" }, "delayEnabled": { "type": "boolean", "example": true, "description": "Enable random delay between emails" }, "delayFrom": { "type": "integer", "example": 10, "description": "Minimum delay in minutes" }, "delayTo": { "type": "integer", "example": 20, "description": "Maximum delay in minutes" }, "stopWhenReplyRecieved": { "type": "boolean", "example": true, "description": "Stop sequence when recipient replies" }, "evergreen": { "type": "boolean", "example": false, "description": "Enable evergreen sequence (continuously running)" }, "bounceThreshold": { "type": "integer", "example": 2, "description": "Number of bounces before pausing" }, "bouncePause": { "type": "boolean", "example": false, "description": "Pause sequence on bounce threshold" }, "autoPause": { "type": "boolean", "example": true, "description": "Enable auto-pause on high bounce rate" }, "autoTagReplies": { "type": "boolean", "example": false, "description": "Auto-tag reply outcomes" }, "emailSendingHours": { "type": "array", "description": "Configure sending hours for each day of the week. Must contain one entry for every day (Monday-Sunday). Each entry needs enabled, name, fromTime and toTime.", "items": { "$ref": "#/components/schemas/EmailSendingHours" }, "example": [ { "enabled": true, "name": "Monday", "fromTime": "09:00", "toTime": "17:00" }, { "enabled": true, "name": "Tuesday", "fromTime": "09:00", "toTime": "17:00" }, { "enabled": true, "name": "Wednesday", "fromTime": "09:00", "toTime": "17:00" }, { "enabled": true, "name": "Thursday", "fromTime": "09:00", "toTime": "17:00" }, { "enabled": true, "name": "Friday", "fromTime": "09:00", "toTime": "17:00" }, { "enabled": false, "name": "Saturday", "fromTime": "09:00", "toTime": "17:00" }, { "enabled": false, "name": "Sunday", "fromTime": "09:00", "toTime": "17:00" } ] }, "sendToOnlyVerifiedEmail": { "type": "boolean", "example": false, "description": "Only send to verified emails" }, "validEmail": { "type": "boolean", "example": true, "description": "Send to contacts with valid email status" }, "riskyEmail": { "type": "boolean", "example": true, "description": "Send to contacts with risky email status" }, "invalidEmail": { "type": "boolean", "example": true, "description": "Send to contacts with invalid email status" }, "checkEmailOpen": { "type": "boolean", "example": false, "description": "Check if recipient opened previous email before sending next" }, "checkEmailClick": { "type": "boolean", "example": false, "description": "Check if recipient clicked link before sending next" }, "checkEmailReply": { "type": "boolean", "example": true, "description": "Check if recipient replied before sending next" }, "checkEmailBeforeSending": { "type": "boolean", "example": true, "description": "Verify email before sending" }, "plainText": { "type": "boolean", "example": true, "description": "Send as plain text email" }, "auto_reply": { "type": "boolean", "example": true, "description": "Enable auto-reply detection" }, "matchProvider": { "type": "boolean", "example": true, "description": "Match sender email provider with recipient" }, "skip_esg": { "type": "boolean", "example": true, "description": "Skip ESG (Email Service Gateway) detection" }, "stopWhenReplyRecievedWhen": { "type": "string", "enum": [ "contact", "contact-with-same-domain" ], "example": "contact", "description": "When to stop sequence on reply" }, "bcc": { "type": "string", "example": "", "description": "BCC email address for all outgoing emails" } } } } } }, "responses": { "200": { "description": "Sequence created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "paused": { "type": "boolean" }, "date_created": { "type": "integer" } } } } } } } } } } }, "/sequences/{id}": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The unique identifier of the sequence" } ], "get": { "summary": "Get a Specific Sequence", "operationId": "get_sequence", "tags": [ "Sequences" ], "description": "Retrieve detailed information about a specific sequence including steps and settings.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Details of the sequence", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "paused": { "type": "boolean" }, "starred": { "type": "boolean" }, "archived": { "type": "boolean" }, "owned_by": { "type": "string", "description": "Email of the sequence owner" }, "lists": { "type": "array", "items": { "type": "string" } }, "senders": { "type": "string", "description": "Comma-separated sender/folder UUIDs" }, "emailSenders": { "type": "array", "description": "Array of selected sender/folder objects derived from senders", "items": { "type": "object" } }, "launchTimingMode": { "type": "string" }, "delayFrom": { "type": "integer" }, "delayTo": { "type": "integer" }, "stopWhenReplyRecieved": { "type": "boolean" }, "evergreen": { "type": "boolean" }, "sent": { "type": "integer" }, "opens": { "type": "integer" }, "clicks": { "type": "integer" }, "replies": { "type": "integer" }, "emailSendingHours": { "type": "array", "description": "Sending hours for each day of the week (Monday-Sunday).", "items": { "$ref": "#/components/schemas/EmailSendingHours" }, "example": [ { "enabled": true, "name": "Monday", "fromTime": "09:00", "toTime": "17:00" }, { "enabled": true, "name": "Tuesday", "fromTime": "09:00", "toTime": "17:00" }, { "enabled": true, "name": "Wednesday", "fromTime": "09:00", "toTime": "17:00" }, { "enabled": true, "name": "Thursday", "fromTime": "09:00", "toTime": "17:00" }, { "enabled": true, "name": "Friday", "fromTime": "09:00", "toTime": "17:00" }, { "enabled": false, "name": "Saturday", "fromTime": "09:00", "toTime": "17:00" }, { "enabled": false, "name": "Sunday", "fromTime": "09:00", "toTime": "17:00" } ] }, "steps": { "type": "array", "items": { "type": "object" } } } } } } } } } } }, "patch": { "summary": "Update Sequence Properties and State", "operationId": "update_sequence", "tags": [ "Sequences" ], "description": "Controls pausing/resuming, starring, and updating sequence settings.\nFor AI agents: Provide steps array to completely rewrite the sequence flow. All existing steps will be replaced.\nUse PUT /sequences/{id}/archive to archive/unarchive sequences.\n", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Sequence name", "example": "Updated Campaign Name" }, "paused": { "type": "boolean", "description": "Pause (true) or resume (false) the sequence", "example": true }, "starred": { "type": "boolean", "description": "Star the sequence", "example": false }, "senders": { "type": "string", "description": "Comma-separated sender/folder UUIDs", "example": "uuid1,uuid2" }, "lists": { "type": "array", "description": "Array of list UUIDs to associate with sequence", "items": { "type": "string" }, "example": [ "list_uuid1" ] }, "launchTimingMode": { "type": "string", "enum": [ "now", "schedule" ], "description": "Launch timing mode", "example": "now" }, "scheduledAt": { "oneOf": [ { "type": "integer", "description": "UTC Timestamp in milliseconds", "example": 1699999999999 }, { "type": "string", "format": "date-time", "description": "ISO 8601 datetime with timezone offset", "example": "2026-07-08T16:30:00+05:30" } ], "description": "Launch time. UTC milliseconds OR ISO 8601 datetime with timezone offset." }, "timezone": { "type": "string", "description": "IANA timezone for sending emails (e.g. 'Asia/Calcutta', 'America/New_York')", "example": "Asia/Calcutta" }, "stopWhenReplyRecieved": { "type": "boolean", "description": "Stop sequence when recipient replies", "example": true }, "evergreen": { "type": "boolean", "description": "Enable evergreen sequence", "example": false }, "delayEnabled": { "type": "boolean", "description": "Enable sending delay", "example": true }, "delayFrom": { "type": "integer", "description": "Minimum delay in minutes", "example": 10 }, "delayTo": { "type": "integer", "description": "Maximum delay in minutes", "example": 20 }, "emailSendingHours": { "type": "array", "description": "Configure sending hours for each day of the week. Must contain one entry for every day (Monday-Sunday). Each entry needs enabled, name, fromTime and toTime.", "items": { "$ref": "#/components/schemas/EmailSendingHours" }, "example": [ { "enabled": true, "name": "Monday", "fromTime": "09:00", "toTime": "17:00" }, { "enabled": true, "name": "Tuesday", "fromTime": "09:00", "toTime": "17:00" }, { "enabled": true, "name": "Wednesday", "fromTime": "09:00", "toTime": "17:00" }, { "enabled": true, "name": "Thursday", "fromTime": "09:00", "toTime": "17:00" }, { "enabled": true, "name": "Friday", "fromTime": "09:00", "toTime": "17:00" }, { "enabled": false, "name": "Saturday", "fromTime": "09:00", "toTime": "17:00" }, { "enabled": false, "name": "Sunday", "fromTime": "09:00", "toTime": "17:00" } ] }, "steps": { "type": "array", "description": "Ordered array of steps - replaces all existing steps", "items": { "$ref": "#/components/schemas/Step" } }, "sendToOnlyVerifiedEmail": { "type": "boolean", "description": "Only send to verified emails" }, "validEmail": { "type": "boolean", "description": "Send to contacts with valid email status" }, "riskyEmail": { "type": "boolean", "description": "Send to contacts with risky email status" }, "invalidEmail": { "type": "boolean", "description": "Send to contacts with invalid email status" }, "checkEmailOpen": { "type": "boolean", "description": "Check if recipient opened previous email" }, "checkEmailClick": { "type": "boolean", "description": "Check if recipient clicked a link in previous email" }, "checkEmailReply": { "type": "boolean", "description": "Check if recipient replied to previous email" }, "checkEmailBeforeSending": { "type": "boolean", "description": "Verify email before sending" }, "plainText": { "type": "boolean", "description": "Send as plain text email" }, "auto_reply": { "type": "boolean", "description": "Enable auto-reply detection" }, "matchProvider": { "type": "boolean", "description": "Match email provider when sending" }, "skip_esg": { "type": "boolean", "description": "Skip ESG detection" }, "stopWhenReplyRecievedWhen": { "type": "string", "enum": [ "contact", "contact-with-same-domain" ], "description": "When to stop sequence on reply" }, "bcc": { "type": "string", "description": "BCC email address for all outgoing emails" } } } } } }, "responses": { "200": { "description": "Sequence updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } } } } }, "/sequences/{id}/stats": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The unique identifier of the sequence" } ], "get": { "summary": "Get Sequence Stats", "operationId": "get_sequence_stats", "tags": [ "Sequence Stats" ], "description": "Retrieve detailed analytics and performance metrics for a sequence.\nFor AI agents: Use from/to query params to filter stats by date range (timestamps in milliseconds).\n", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "query", "name": "from", "schema": { "type": "integer" }, "description": "Start date timestamp (Unix ms) for date range filtering" }, { "in": "query", "name": "to", "schema": { "type": "integer" }, "description": "End date timestamp (Unix ms) for date range filtering" }, { "in": "query", "name": "sender", "schema": { "type": "string" }, "description": "Filter stats by specific sender email" } ], "responses": { "200": { "description": "Provides sent, opens, clicks, and lead progress breakdown", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "sent": { "type": "integer", "example": 1500 }, "opens": { "type": "integer", "example": 750 }, "clicks": { "type": "integer", "example": 130 }, "replies": { "type": "integer", "example": 45 }, "sequenceStats": { "type": "object", "properties": { "leadsTotal": { "type": "integer", "example": 2000 }, "leadsNotStarted": { "type": "integer", "example": 500 }, "leadsInProgress": { "type": "integer", "example": 1000 }, "leadsCompleted": { "type": "integer", "example": 450 }, "leadsBlocked": { "type": "integer", "example": 50 } } } } } } } } } } } } }, "/sequences/{id}/clone": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The unique identifier of the sequence to clone" } ], "post": { "summary": "Clone a Sequence", "operationId": "clone_sequence", "tags": [ "Sequences" ], "description": "Create a copy of an existing sequence.\nFor AI agents: The cloned sequence will be in paused state. You need to update paused=false to activate.\n", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Sequence cloned successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } } } } } } } } } }, "/sequences/{id}/archive": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The unique identifier of the sequence" } ], "put": { "summary": "Archive or Unarchive a Sequence", "operationId": "archive_sequence", "tags": [ "Sequences" ], "description": "Archive or unarchive a sequence. Archiving pauses the sequence and removes pending tasks.\nFor AI agents: Archiving is the recommended way to stop a sequence rather than deletion.\n", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "archived": { "type": "boolean", "default": true, "description": "true to archive, false to unarchive" } } } } } }, "responses": { "200": { "description": "Sequence archived/unarchived successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } } } } }, "/users": { "get": { "summary": "Get All Users", "operationId": "get_all_users", "tags": [ "Users" ], "description": "Retrieve all users in your workspace.\nFor AI agents: Only owners and admins can view all users. Regular users see limited info.\n", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 100, "maximum": 100 }, "description": "Maximum number of users to return" }, { "in": "query", "name": "skip", "schema": { "type": "integer", "default": 0 }, "description": "Number of users to skip for pagination" }, { "in": "query", "name": "search", "schema": { "type": "string" }, "description": "Search query to filter users" }, { "in": "query", "name": "starred", "schema": { "type": "boolean" }, "description": "Filter by starred status" }, { "in": "query", "name": "archived", "schema": { "type": "boolean" }, "description": "Filter by archived status" } ], "responses": { "200": { "description": "A list of users", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string" }, "date_created": { "type": "string", "format": "date-time" } } } } } } } } } } }, "post": { "summary": "Add a User", "operationId": "add_user", "tags": [ "Users" ], "description": "Invite a new user to your account.\nFor AI agents: Only owners and admins can add users. Role must be one of: client, user, admin, developer.\nAn invitation email will be sent to the user.\n", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "example": "john@example.com", "description": "Email address of the new user (required)" }, "role": { "type": "string", "enum": [ "client", "user", "admin", "developer" ], "example": "user", "description": "User role. client=external client access, user=regular team member, admin=full access, developer=API access" }, "url": { "type": "string", "example": "https://example.com/dashboard", "description": "Optional URL to redirect after accepting invitation" } } } } } }, "responses": { "200": { "description": "User added successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/users/{id}": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The unique identifier of the user" } ], "get": { "summary": "Get a Specific User", "operationId": "get_user", "tags": [ "Users" ], "description": "Retrieve detailed information about a specific team member.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Details of the user", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string" } } } } } } } } } }, "patch": { "summary": "Update a User", "operationId": "update_user", "tags": [ "Users" ], "description": "Update user properties including name and role.\nFor AI agents: To remove a user, set archived=true via the appropriate archive endpoint.\n", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "User's display name", "example": "John Doe" }, "role": { "type": "string", "enum": [ "client", "user", "admin", "developer" ], "description": "User role", "example": "user" } } } } } }, "responses": { "200": { "description": "User updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } } } } }, "/senders": { "get": { "summary": "Get All Email Senders", "operationId": "get_all_senders", "tags": [ "Senders" ], "description": "Retrieve all email sending accounts (senders) in your workspace.\nFor AI agents: Senders are email accounts used to send sequence emails. Filter by status to find healthy senders.\n", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 100, "maximum": 100 }, "description": "Maximum number of senders to return" }, { "in": "query", "name": "skip", "schema": { "type": "integer", "default": 0 }, "description": "Number of senders to skip for pagination" }, { "in": "query", "name": "search", "schema": { "type": "string" }, "description": "Search query to filter senders by email/name" }, { "in": "query", "name": "folder_id", "schema": { "type": "string" }, "description": "Filter by folder ID" }, { "in": "query", "name": "owned_by", "schema": { "type": "string" }, "description": "Filter by owner (admin/owner only)" }, { "in": "query", "name": "has_error", "schema": { "type": "boolean" }, "description": "Filter by error status" }, { "in": "query", "name": "connecting", "schema": { "type": "boolean" }, "description": "Filter by connecting status" }, { "in": "query", "name": "connected", "schema": { "type": "boolean" }, "description": "Filter by connected status" }, { "in": "query", "name": "warmup_active", "schema": { "type": "boolean" }, "description": "Filter by warmup active status" }, { "in": "query", "name": "warmup_paused", "schema": { "type": "boolean" }, "description": "Filter by warmup paused status" }, { "in": "query", "name": "no_custom_tracking_domain", "schema": { "type": "boolean" }, "description": "Filter senders without custom tracking domain" } ], "responses": { "200": { "description": "A list of email senders grouped by folder", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "folder": { "type": "object", "nullable": true, "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "senders": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "owned_by": { "type": "string", "description": "Email of the sender owner" }, "date_created": { "type": "string", "format": "date-time" } } } } } } } } } } } } } }, "post": { "summary": "Add Single Sender (SMTP/IMAP only)", "operationId": "add_single_sender", "tags": [ "Senders" ], "description": "Add a single email sender via SMTP/IMAP. The caller must provide the real password and SMTP/IMAP server details; placeholder values are not accepted. For Gmail and Outlook, OAuth is preferred (use POST /oauth/google or POST /oauth/outlook). SMTP/IMAP can still be used if the user explicitly provides SMTP/IMAP credentials.", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "smtpHost", "smtpPort", "smtpPassword" ], "properties": { "email": { "type": "string", "format": "email", "description": "Sender email address" }, "senderName": { "type": "string", "description": "Display name for the sender" }, "smtpHost": { "type": "string", "description": "SMTP server hostname" }, "smtpPort": { "type": "integer", "description": "SMTP server port" }, "smtpUsername": { "type": "string", "description": "SMTP username (defaults to email)" }, "smtpPassword": { "type": "string", "description": "SMTP/IMAP password" }, "imapHost": { "type": "string", "description": "IMAP server hostname (omit for SMTP-only senders)" }, "imapPort": { "type": "integer", "description": "IMAP server port (defaults to 993)" }, "imapUsername": { "type": "string", "description": "IMAP username (if different from SMTP)" }, "imapPassword": { "type": "string", "description": "IMAP password (if different from SMTP)" }, "folder": { "type": "string", "description": "Folder ID to organize the sender" } } } } } }, "responses": { "200": { "description": "Sender added successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } } } } }, "/senders/bulk": { "post": { "summary": "Add Bulk Senders", "operationId": "add_bulk_senders", "tags": [ "Senders" ], "description": "Add multiple email senders at once using a CSV file or JSON array.\nFor AI agents: CSV should have columns like email, password, smtpHost, smtpPort, etc.\n", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "CSV file containing sender credentials" }, "senders": { "type": "array", "description": "Alternative to file - array of sender objects", "items": { "type": "object" } } } } } } }, "responses": { "200": { "description": "Bulk senders upload initiated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "bulkID": { "type": "string", "description": "ID to track the bulk upload progress" } } } } } } } } } } }, "/oauth/google": { "post": { "summary": "Initialize Google OAuth", "operationId": "initialize_google_oauth", "tags": [ "OAuth" ], "description": "Get the OAuth URL for connecting a Google (Gmail/G Suite) account.\nFor AI agents: Redirect the user to the returned URL or open it in a browser. After OAuth completion, the sender will be connected.\n", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "redirectUrl": { "type": "string", "description": "URL to redirect after OAuth completion" } } } } } }, "responses": { "200": { "description": "OAuth URL generated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "url": { "type": "string", "description": "Google OAuth URL to open" } } } } } } } } } } }, "/oauth/outlook": { "post": { "summary": "Initialize Outlook OAuth", "operationId": "initialize_outlook_oauth", "tags": [ "OAuth" ], "description": "Get the OAuth URL for connecting a Microsoft Outlook account.\nFor AI agents: Redirect the user to the returned URL or open it in a browser.\n", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "redirectUrl": { "type": "string", "description": "URL to redirect after OAuth completion" } } } } } }, "responses": { "200": { "description": "OAuth URL generated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "url": { "type": "string", "description": "Microsoft OAuth URL to open" } } } } } } } } } } }, "/folders": { "get": { "summary": "Get All Folders", "operationId": "get_all_folders", "tags": [ "Folders" ], "description": "Retrieve all folders for organizing lists, templates, sequences, and senders.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 100 }, "description": "Maximum number of folders to return" }, { "in": "query", "name": "skip", "schema": { "type": "integer", "default": 0 }, "description": "Number of folders to skip for pagination" }, { "in": "query", "name": "search", "schema": { "type": "string" }, "description": "Search query to filter folders" }, { "in": "query", "name": "type", "schema": { "type": "string", "enum": [ "list", "template", "sequence", "email-sender" ] }, "description": "Type of the folder" } ], "responses": { "200": { "description": "A list of folders", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "owned_by": { "type": "string", "description": "Email of the folder owner" }, "date_created": { "type": "string", "format": "date-time" } } } } } } } } } } }, "post": { "summary": "Create a Folder", "operationId": "create_folder", "tags": [ "Folders" ], "description": "Create a new folder to organize lists, templates, sequences, or senders.", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "type" ], "properties": { "name": { "type": "string", "description": "Name of the folder" }, "type": { "type": "string", "enum": [ "list", "template", "sequence", "email-sender" ], "description": "Type of items this folder will contain" } } } } } }, "responses": { "200": { "description": "Folder created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" } } } } } } } } } } }, "/contacts": { "post": { "summary": "Add Leads to a List", "operationId": "add_contacts", "tags": [ "Leads" ], "description": "Add multiple leads (contacts) to an existing list.\nFor AI agents: Maximum 500 leads per request. Set remove_duplicates=true to maintain list quality.\nUse standard fields like First_Name, Last_Name, Email, Phone, plus any custom fields.\n", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "list_id", "contacts" ], "properties": { "list_id": { "type": "string", "description": "The list ID to add leads to", "example": "list_uuid_here" }, "contacts": { "type": "array", "description": "Array of lead objects to add (max 500)", "items": { "type": "object", "required": [ "Email" ], "properties": { "First_Name": { "type": "string", "description": "Lead's first name" }, "Last_Name": { "type": "string", "description": "Lead's last name" }, "Email": { "type": "string", "format": "email", "description": "Lead's email address (required)" }, "Phone": { "type": "string", "description": "Lead's phone number" } } }, "example": [ { "First_Name": "John", "Last_Name": "Doe", "Email": "john@example.com", "Phone": "+1234567890", "Company": "Acme Inc" } ] }, "remove_duplicates": { "type": "boolean", "description": "Automatically remove duplicate emails from the list", "example": false } } } } } }, "responses": { "200": { "description": "Leads added successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } } } } }, "400": { "description": "Bad request - invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/contacts/remove": { "post": { "summary": "Remove a Lead from a List", "operationId": "remove_contact", "tags": [ "Leads" ], "description": "Remove a single lead from a list by their email address.", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "list_id", "email" ], "properties": { "list_id": { "type": "string", "description": "The list ID", "example": "list_uuid_here" }, "email": { "type": "string", "format": "email", "description": "The email address of the lead to remove", "example": "john@example.com" } } } } } }, "responses": { "200": { "description": "Lead removed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } } } } } } } }, "/leads/{id}": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The unique identifier of the lead (contact)" } ], "patch": { "summary": "Update a Lead", "operationId": "update_lead", "tags": [ "Leads" ], "description": "Update lead properties.\nFor AI agents: You can update any custom fields. System fields like _id, accuracy, verification status cannot be modified.\n", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "First_Name": { "type": "string" }, "Last_Name": { "type": "string" }, "Email": { "type": "string", "format": "email" }, "Phone": { "type": "string" }, "Company": { "type": "string" }, "Title": { "type": "string" } } } } } }, "responses": { "200": { "description": "Lead updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "description": "Updated fields" } } } } } } } } }, "/leads/{id}/move": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The unique identifier of the lead to move" } ], "put": { "summary": "Move Lead to Another List", "operationId": "move_lead", "tags": [ "Leads" ], "description": "Move a lead from one list to another.", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "list_id" ], "properties": { "list_id": { "type": "string", "description": "Destination list ID" } } } } } }, "responses": { "200": { "description": "Lead moved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } } } } }, "/contacts/{id}/archive": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The unique identifier of the contact (MongoDB ObjectId)" } ], "put": { "summary": "Archive or Unarchive a Contact", "operationId": "archive_contact", "tags": [ "Leads" ], "description": "Archive or unarchive a contact. Archiving removes pending tasks for this contact.", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "archived": { "type": "boolean", "default": true, "description": "true to archive, false to unarchive" } } } } } }, "responses": { "200": { "description": "Contact archived/unarchived successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } } } } }, "/sent": { "get": { "summary": "Get Sent Activity", "operationId": "get_sent_activity", "tags": [ "Activity" ], "description": "Retrieve a log of all sent emails across your sequences.\nFor AI agents: Use since parameter to get recent activity. Results are paginated.\n", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "query", "name": "per_page", "schema": { "type": "integer", "default": 100, "maximum": 100 }, "description": "Number of results per page (max 100)" }, { "in": "query", "name": "page", "schema": { "type": "integer", "default": 1 }, "description": "Page number" }, { "in": "query", "name": "sequence_id", "schema": { "type": "string" }, "description": "Filter by sequence ID" }, { "in": "query", "name": "recipient_email_address", "schema": { "type": "string" }, "description": "Filter by recipient email" }, { "in": "query", "name": "since", "schema": { "type": "integer" }, "description": "Filter events since timestamp (Unix timestamp in milliseconds)", "example": 1704067200000 }, { "in": "query", "name": "from", "schema": { "type": "integer" }, "description": "Start date timestamp (Unix ms) for date range" }, { "in": "query", "name": "to", "schema": { "type": "integer" }, "description": "End date timestamp (Unix ms) for date range" } ], "responses": { "200": { "description": "Sent activity retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "time": { "type": "integer" }, "message": { "type": "string" }, "type": { "type": "string" }, "sequence": { "type": "string" }, "email": { "type": "string" }, "sequence_name": { "type": "string" } } } } } } } } } }, "/opens": { "get": { "summary": "Get Opens Activity", "operationId": "get_opens_activity", "tags": [ "Activity" ], "description": "Retrieve email open events to measure engagement.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "query", "name": "per_page", "schema": { "type": "integer", "default": 100, "maximum": 100 }, "description": "Number of results per page (max 100)" }, { "in": "query", "name": "page", "schema": { "type": "integer", "default": 1 }, "description": "Page number" }, { "in": "query", "name": "sequence_id", "schema": { "type": "string" }, "description": "Filter by sequence ID" }, { "in": "query", "name": "recipient_email_address", "schema": { "type": "string" }, "description": "Filter by recipient email" }, { "in": "query", "name": "since", "schema": { "type": "integer" }, "description": "Filter events since timestamp (Unix ms)" }, { "in": "query", "name": "from", "schema": { "type": "integer" }, "description": "Start date timestamp (Unix ms)" }, { "in": "query", "name": "to", "schema": { "type": "integer" }, "description": "End date timestamp (Unix ms)" } ], "responses": { "200": { "description": "Opens activity retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "time": { "type": "integer" }, "message": { "type": "string" }, "type": { "type": "string" }, "sequence": { "type": "string" }, "email": { "type": "string" }, "sequence_name": { "type": "string" } } } } } } } } } }, "/clicks": { "get": { "summary": "Get Clicks Activity", "operationId": "get_clicks_activity", "tags": [ "Activity" ], "description": "Retrieve link click events to measure engagement.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "query", "name": "per_page", "schema": { "type": "integer", "default": 100, "maximum": 100 } }, { "in": "query", "name": "page", "schema": { "type": "integer", "default": 1 } }, { "in": "query", "name": "sequence_id", "schema": { "type": "string" } }, { "in": "query", "name": "recipient_email_address", "schema": { "type": "string" } }, { "in": "query", "name": "since", "schema": { "type": "integer" } }, { "in": "query", "name": "from", "schema": { "type": "integer" } }, { "in": "query", "name": "to", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Clicks activity retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "time": { "type": "integer" }, "message": { "type": "string" }, "type": { "type": "string" }, "sequence": { "type": "string" }, "email": { "type": "string" }, "sequence_name": { "type": "string" }, "template_name": { "type": "string" } } } } } } } } } }, "/replies": { "get": { "summary": "Get Replies Activity", "operationId": "get_replies_activity", "tags": [ "Activity" ], "description": "Retrieve email reply events to track responses.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "query", "name": "per_page", "schema": { "type": "integer", "default": 100, "maximum": 100 } }, { "in": "query", "name": "page", "schema": { "type": "integer", "default": 1 } }, { "in": "query", "name": "sequence_id", "schema": { "type": "string" } }, { "in": "query", "name": "recipient_email_address", "schema": { "type": "string" } }, { "in": "query", "name": "since", "schema": { "type": "integer" } }, { "in": "query", "name": "from", "schema": { "type": "integer" } }, { "in": "query", "name": "to", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Replies activity retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "time": { "type": "integer" }, "message": { "type": "string" }, "type": { "type": "string" }, "sequence": { "type": "string" }, "email": { "type": "string" }, "sequence_name": { "type": "string" }, "template_name": { "type": "string" } } } } } } } } } }, "/workspaces": { "get": { "summary": "Get All Workspaces", "operationId": "get_all_workspaces", "tags": [ "Workspaces" ], "description": "Retrieve all workspaces the authenticated user has access to.\nFor AI agents: Only workspace owners can view all workspaces. Shows workspace name, ID, and user's permission level.\n", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "List of workspaces", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "permission": { "type": "string", "enum": [ "owner", "admin", "user", "client" ] } } } } } } } } } } }, "post": { "summary": "Create Workspace", "operationId": "create_workspace", "tags": [ "Workspaces" ], "description": "Create a new workspace.\nFor AI agents: Only workspace owners can create new workspaces. Name must be at least 4 characters.\n", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 4, "description": "Name of the workspace (min 4 characters)" } } } } } }, "responses": { "200": { "description": "Workspace created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } } } } } } } } } }, "/workspaces/{id}": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The unique identifier of the workspace" } ], "patch": { "summary": "Update Workspace", "operationId": "update_workspace", "tags": [ "Workspaces" ], "description": "Update workspace name. Only owners can update workspaces.", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 4, "description": "New name for the workspace (min 4 characters)" } } } } } }, "responses": { "200": { "description": "Workspace updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } } } } }, "/inbox-placement": { "get": { "summary": "Get Inbox Placement Tests", "operationId": "get_inbox_placement_tests", "tags": [ "Inbox Placement" ], "description": "Retrieve all inbox placement tests.\nFor AI agents: Inbox placement tests help verify email deliverability across different providers.\n", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 100, "maximum": 100 } }, { "in": "query", "name": "skip", "schema": { "type": "integer", "default": 0 } }, { "in": "query", "name": "owned_by", "schema": { "type": "string" }, "description": "Filter by owner (admin/owner only)" } ], "responses": { "200": { "description": "List of inbox placement tests", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "owned_by": { "type": "string" } } } } } } } } } } }, "post": { "summary": "Create Inbox Placement Test", "operationId": "create_inbox_placement_test", "tags": [ "Inbox Placement" ], "description": "Create a new inbox placement test to check email deliverability.\nFor AI agents: Tests can use sequence content or custom subject/body. Use source='from-salesblink' with subject/body for custom content.\n", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "from-salesblink", "sequence" ], "description": "Source of test content" }, "subject": { "type": "string", "description": "Subject line (for from-salesblink source with custom content)" }, "body": { "type": "string", "description": "Email body HTML (for from-salesblink source)" }, "sequence_id": { "type": "string", "description": "Sequence ID to test (for sequence source)" }, "email_senders": { "type": "array", "description": "Array of email senders and/or folders to send test emails from. Provide either individual senders, folders, or both. Folders are expanded server-side into all senders they contain. Duplicates across folders and individual selections are automatically removed.", "items": { "type": "object", "required": ["key", "value", "label", "serviceName"], "properties": { "key": { "type": "string", "description": "UUID of the folder or sender (same as value). For folders this is the folder UUID; for individual senders this is the sender UUID." }, "value": { "type": "string", "description": "UUID of the folder or sender (same as key). The UUID used by the server to resolve the sender or folder." }, "label": { "type": "string", "description": "Human-readable display label (e.g. folder name or sender email address). Used for UI/audit only." }, "serviceName": { "type": "string", "description": "Type of selection. MUST be 'folder' for folders. For individual senders use the sender's provider such as 'gmail', 'outlook', or 'smtpimap'." } } } } } } } } }, "responses": { "200": { "description": "Test created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } } } } } } } } } }, "/inbox-placement/{id}/pause": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The unique identifier of the test" } ], "put": { "summary": "Pause Inbox Placement Test", "operationId": "pause_inbox_placement_test", "tags": [ "Inbox Placement" ], "description": "Pause an active inbox placement test.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Test paused successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } } } } }, "/inbox-placement/{id}": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The unique identifier of the test" } ], "delete": { "summary": "Delete Inbox Placement Test", "operationId": "delete_inbox_placement_test", "tags": [ "Inbox Placement" ], "description": "Delete an inbox placement test.", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Test deleted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } } } } }, "/reports": { "get": { "summary": "Get Reports", "operationId": "get_reports", "tags": [ "Reports" ], "description": "Retrieve activity reports with filtering.\nFor AI agents: Use from/to parameters for date range filtering.\n", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 100, "maximum": 100 } }, { "in": "query", "name": "skip", "schema": { "type": "integer", "default": 0 } }, { "in": "query", "name": "from", "schema": { "type": "integer" }, "description": "Start date timestamp (Unix ms)" }, { "in": "query", "name": "to", "schema": { "type": "integer" }, "description": "End date timestamp (Unix ms)" }, { "in": "query", "name": "owned_by", "schema": { "type": "string" }, "description": "Filter by owner (admin/owner only)" } ], "responses": { "200": { "description": "Reports retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object" } } } } } } } } } }, "/domains": { "get": { "summary": "Get Custom Domains", "operationId": "get_custom_domains", "tags": [ "Domains" ], "description": "Retrieve all custom tracking domains configured in the workspace.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 100 } }, { "in": "query", "name": "skip", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "List of custom domains", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "domain": { "type": "string" }, "type": { "type": "string", "enum": [ "click-tracker", "redirect" ] }, "verified": { "type": "boolean" }, "owned_by": { "type": "string" } } } } } } } } } } } }, "/signatures": { "get": { "summary": "Get Email Signatures", "operationId": "get_signatures", "tags": [ "Signatures" ], "description": "Retrieve all email signatures configured in the workspace.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 100 } }, { "in": "query", "name": "skip", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "List of email signatures", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "content": { "type": "string" }, "owned_by": { "type": "string" } } } } } } } } } } } }, "/warmup-links": { "get": { "summary": "Get Warmup Links", "operationId": "get_warmup_links", "tags": [ "Senders" ], "description": "Retrieve all warmup link configurations.", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 100 } }, { "in": "query", "name": "skip", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "List of warmup links", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object" } } } } } } } } } }, "/keys": { "get": { "summary": "Get API Keys", "operationId": "get_api_keys", "tags": [ "API Keys" ], "description": "Retrieve all API keys for the account. Use this to audit active integrations or find key IDs for management.\n", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "List of API keys", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "0d061c26-83a5-490c-ab85-c72e46103e21" }, "name": { "type": "string", "example": "test" }, "key": { "type": "string", "example": "key...31f" }, "date_created": { "type": "string", "format": "date-time", "example": "2026-05-08T05:05:48.672Z" }, "active": { "type": "boolean", "example": true }, "user_id": { "type": "string", "example": "772e7879-cb1f-4cc6-9dae-50b3962d302a" }, "owned_by": { "type": "string", "format": "email", "example": "user@example.com" } } } } } } } } } } }, "post": { "summary": "Create API Key", "operationId": "create_api_key", "tags": [ "API Keys" ], "description": "Generate a new API key. The full key is only returned once in the response; store it securely.\n", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "example": "New Integration" } } } } } }, "responses": { "200": { "description": "API key created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "data": { "type": "object", "properties": { "id": { "type": "string", "example": "0d061c26-83a5-490c-ab85-c72e46103e21" }, "name": { "type": "string", "example": "test" }, "api_key": { "type": "string", "example": "key-5f3e..." }, "date_created": { "type": "string", "format": "date-time", "example": "2026-05-08T05:05:48.672Z" } } } } } } } } } } }, "/keys/{id}/refresh": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "post": { "summary": "Refresh API Key", "operationId": "refresh_api_key", "tags": [ "API Keys" ], "description": "Generate a new API key and revoke the old one. This is useful for rotating keys without losing the key record's name/metadata.\n", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "API key refreshed", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "API key refreshed" }, "data": { "type": "object", "properties": { "id": { "type": "string", "example": "0d061c26-83a5-490c-ab85-c72e46103e21" }, "name": { "type": "string", "example": "test" }, "api_key": { "type": "string", "example": "key-5f3e..." }, "date_created": { "type": "string", "format": "date-time", "example": "2026-05-08T05:05:48.672Z" } } } } } } } } } } }, "/keys/{id}": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "delete": { "summary": "Delete API Key", "operationId": "delete_api_key", "tags": [ "API Keys" ], "description": "Revoke an API key. This action is irreversible. You cannot delete the key currently used for authentication.\n", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "API key deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } } } } }, "/senders/{id}": { "patch": { "summary": "Update Sender", "operationId": "update_sender", "tags": [ "Senders" ], "description": "Update email sender settings including warmup, inbox, signature, tracking domain, and sequence sending configuration.\nOnly the fields provided are updated.\n", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" }, "description": "The sender ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "warmup_enabled": { "type": "boolean", "description": "Enable/disable warmup" }, "warmup_urls": { "type": "array", "items": { "type": "string" }, "description": "Warmup link URLs" }, "warmup_templates": { "type": "array", "items": { "type": "string" }, "description": "Warmup template IDs" }, "auto_ramp_up_enabled": { "type": "boolean", "description": "Enable auto ramp-up" }, "ramp_up_frequency": { "type": "integer", "description": "Ramp-up increment" }, "max_daily_frequency": { "type": "integer", "description": "Max daily warmup emails" }, "starting_warmup_frequency": { "type": "integer", "description": "Starting warmup frequency" }, "open_rate": { "type": "integer", "description": "Target open rate percentage" }, "spam_protection": { "type": "integer", "description": "Spam protection level" }, "read_emulation": { "type": "integer", "description": "Read emulation level" }, "warmup_keyword": { "type": "string", "description": "Warmup keyword/tag" }, "sequence_auto_ramp_up_enabled": { "type": "boolean", "description": "Enable sequence auto ramp-up" }, "sequence_initial_daily_frequency": { "type": "integer", "description": "Initial daily sequence sends" }, "sequence_ramp_up_frequency": { "type": "integer", "description": "Sequence ramp-up increment" }, "sequence_max_daily_frequency": { "type": "integer", "description": "Max daily sequence sends" }, "pause_cold_emails_when_health_low": { "type": "boolean", "description": "Pause cold emails when health is low" }, "pause_cold_emails_health_threshold": { "type": "integer", "description": "Health threshold to pause at" }, "inbox_enabled": { "type": "boolean", "description": "Enable inbox monitoring" }, "inbox_path": { "type": "string", "description": "Inbox folder path" }, "spam_path": { "type": "string", "description": "Spam folder path" }, "signature": { "type": "string", "description": "Signature ID or name" }, "reply_to": { "type": "string", "description": "Reply-to email address" }, "dkim_identifier": { "type": "string", "description": "DKIM identifier" }, "use_custom_tracking_domain": { "type": "boolean", "description": "Use custom tracking domain" }, "tracking_domain": { "type": "string", "description": "Tracking domain ID" } } } } } }, "responses": { "200": { "description": "Sender updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } } } } }, "/billing/add-card": { "post": { "summary": "Get Add Card Login Link", "operationId": "get_add_card_login_link", "tags": [ "Billing" ], "description": "Generate a magic login link that redirects the user to the billing page to add a payment card.\n", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Login link generated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "login_link": { "type": "string" }, "destination": { "type": "string" }, "purpose": { "type": "string" } } } } } } } } } } }, "/billing/remove-card": { "post": { "summary": "Get Remove Card Login Link", "operationId": "get_remove_card_login_link", "tags": [ "Billing" ], "description": "Generate a magic login link that redirects the user to the billing page to remove their saved payment card.\n", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Login link generated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "login_link": { "type": "string" }, "destination": { "type": "string" }, "purpose": { "type": "string" } } } } } } } } } } }, "/domains/search": { "get": { "summary": "Search Domains", "operationId": "search_domains", "tags": [ "Domains" ], "description": "Search available .com domains for DFY purchase. Only .com TLD is supported.\n", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "query", "name": "keyword", "required": true, "schema": { "type": "string" }, "description": "Domain keyword to search (e.g. 'mybrand'). Only .com is supported." } ], "responses": { "200": { "description": "Domain search results", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "price": { "type": "number" }, "status": { "type": "string", "enum": [ "available", "unavailable" ] }, "google_workspace_available": { "type": "boolean" }, "ms365_workspace_available": { "type": "boolean" } } } } } } } } } } } }, "/dfy/orders": { "post": { "summary": "Place DFY Order", "operationId": "place_dfy_order", "tags": [ "DFY" ], "description": "Purchase domains and provision Google Workspace, Outlook, or Azure mailboxes with full deliverability setup.\nRequires a saved payment method. Trial plans are not eligible.\n\n**Provider-specific requirements:**\n- **Google**: password is required. mailboxes array is required for buy domains.\n- **Outlook**: mailboxes array is required for buy domains.\n- **Azure**: mailboxCount is required and must be a exactly 100 i.e. 100 mailboxes per domain in case of Azure.\n", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domains", "type" ], "properties": { "domains": { "type": "array", "description": "Array of domain objects. Buy and Connect domains cannot be mixed in the same order.", "items": { "type": "object", "required": [ "domain" ], "properties": { "domain": { "type": "string", "description": "Domain name to purchase or connect" }, "isConnect": { "type": "boolean", "description": "true = connect your own existing domain (no purchase), false = buy new domain (default)" }, "mailboxes": { "type": "array", "description": "Mailboxes to provision. Required for google/outlook buy domains. Optional for connect-domain orders.", "items": { "type": "object", "required": [ "username" ], "properties": { "username": { "type": "string", "description": "Mailbox username (without @domain)" }, "firstName": { "type": "string" }, "lastName": { "type": "string" } } } } } } }, "type": { "type": "string", "enum": [ "google", "outlook", "azure" ], "description": "Mailbox provider type. google = Google Workspace, outlook = Microsoft 365, azure = Azure (100 mailboxes per domain)" }, "redirectionUrl": { "type": "string", "description": "Redirect URL for the domain" }, "masterInboxEmail": { "type": "string", "description": "Master inbox email for admin access" }, "password": { "type": "string", "description": "Common password for ALL mailboxes. REQUIRED for google. Auto-generated if omitted for google buy domains with no custom mailboxes." }, "couponCode": { "type": "string", "description": "Optional Stripe coupon code" } } } } } }, "responses": { "200": { "description": "DFY order placed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object" }, "notice": { "type": "string" } } } } } } } }, "get": { "summary": "Get DFY Orders", "operationId": "get_dfy_orders", "tags": [ "DFY" ], "description": "Retrieve all Done-For-You orders.\n", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "List of DFY orders", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "array", "items": { "type": "object" } } } } } } } } } }, "/dfy/orders/{orderId}/mailboxes": { "post": { "summary": "Add Mailbox to DFY Order", "operationId": "add_dfy_mailbox", "tags": [ "DFY" ], "description": "Add mailboxes to an existing DFY order. Cannot be used for Azure orders.\n", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "path", "name": "orderId", "required": true, "schema": { "type": "string" }, "description": "The DFY order ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domainName", "emails" ], "properties": { "domainName": { "type": "string", "description": "Domain in the order to add mailboxes to" }, "emails": { "type": "array", "items": { "type": "string" }, "description": "Array of usernames (without @domain)" }, "password": { "type": "string", "description": "Password for new mailboxes (Google only)" } } } } } }, "responses": { "200": { "description": "Mailbox added successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponse" } } } } } } }, "/dfy/orders/{orderId}/mailboxes/{mailboxId}": { "delete": { "summary": "Cancel DFY Mailbox", "operationId": "cancel_dfy_mailbox", "tags": [ "DFY" ], "description": "Cancel a mailbox from a DFY order. Returns a billing management login link.\n", "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "path", "name": "orderId", "required": true, "schema": { "type": "string" }, "description": "The DFY order ID" }, { "in": "path", "name": "mailboxId", "required": true, "schema": { "type": "string" }, "description": "The mailbox ID (inboxkit_mailbox_uid) to cancel" } ], "responses": { "200": { "description": "Billing management link returned", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "login_link": { "type": "string" }, "destination": { "type": "string" }, "purpose": { "type": "string" } } } } } } } } } } } } }