openapi: 3.0.3 info: title: 'Postmaster+ API Documentation' description: '' version: 1.0.0 servers: - url: 'https://postmasterplus.app' tags: - name: Intelligence description: '' - name: Blocklists description: '' - name: Endpoints description: '' - name: Tools description: '' components: securitySchemes: default: type: http scheme: bearer description: 'You can retrieve your token by visiting your dashboard and clicking Team Settings > API Tokens.' security: - default: [] paths: '/api/v1/intelligence/single-emails/{email}': get: summary: 'Retrieve Single Email.' operationId: retrieveSingleEmail description: '' parameters: [] responses: 200: description: '' content: application/json: schema: type: object example: data: id: 125 email: eloisa.harber@example.com status: null created_at: '2026-01-15 14:15:31' updated_at: '2026-01-15 14:15:31' properties: data: type: object properties: id: type: integer example: 125 email: type: string example: eloisa.harber@example.com status: type: string example: null created_at: type: string example: '2026-01-15 14:15:31' updated_at: type: string example: '2026-01-15 14:15:31' tags: - Intelligence delete: summary: 'Delete Single Email.' operationId: deleteSingleEmail description: '' parameters: [] responses: 200: description: '' content: application/json: schema: type: object example: message: 'Single email deleted.' deleted: true properties: message: type: string example: 'Single email deleted.' deleted: type: boolean example: true tags: - Intelligence parameters: - in: path name: email description: 'The email address to retrieve.' example: example@postmasterplus.com required: true schema: type: string /api/v1/intelligence/single-emails/scan: post: summary: 'Scan Single Email.' operationId: scanSingleEmail description: '' parameters: [] responses: { } tags: - Intelligence requestBody: required: true content: application/json: schema: type: object properties: email: type: string description: 'The email address to scan.' example: example@postmasterplus.com actions: type: string description: 'The actions in comma separated format to perform.' example: '"verification,activity,postal_append"' required: - email - actions /api/v1/blocklist/scan/start: post: summary: 'Start Blocklist Scan.' operationId: startBlocklistScan description: '' parameters: [] responses: 200: description: '' content: application/json: schema: oneOf: - description: '' type: object example: data: id: 01kf105wf59wkretaykfbgw0p1 status: pending unique_hosts_checked: 1 total_hosts_detected: null urls_scanned: 0 urls_skipped: 0 blocklisted: false credits_used: 0 error_message: '' started_at: null completed_at: null success: true message: 'Blocklist check started successfully.' properties: data: type: object properties: id: type: string example: 01kf105wf59wkretaykfbgw0p1 description: 'The unique identifier for the blocklist check.' enum: [] status: type: string example: pending description: 'The status of the blocklist check. Example: `pending`, `processing`, `completed`, `partially_completed`, `failed`' enum: - pending - processing - completed - partially_completed - failed unique_hosts_checked: type: integer example: 1 description: 'The number of unique hosts checked.' enum: [] total_hosts_detected: type: string example: null description: 'The number of hosts detected.' enum: [] urls_scanned: type: integer example: 0 description: 'The number of URLs scanned.' enum: [] urls_skipped: type: integer example: 0 description: 'The number of URLs skipped.' enum: [] blocklisted: type: boolean example: false description: 'Whether the check is blocklisted.' enum: [] credits_used: type: integer example: 0 description: 'The number of credits used.' enum: [] error_message: type: string example: '' description: 'The error message if the check failed.' enum: [] started_at: type: string example: null description: 'The date and time the check started.' enum: [] completed_at: type: string example: null description: 'The date and time the check completed.' enum: [] required: - id - status - unique_hosts_checked - total_hosts_detected - urls_scanned - urls_skipped - blocklisted - credits_used - error_message - started_at - completed_at success: type: boolean example: true description: 'Whether the request was successful.' enum: [] message: type: string example: 'Blocklist check started successfully.' description: 'The message of the response.' enum: [] required: - success - message - description: '' type: object example: success: true message: 'Blocklist check started successfully.' data: id: 01ARZ3NDEKTSV4RRFFQ69G5FAV status: pending unique_hosts_checked: 0 total_hosts_detected: null urls_scanned: 0 urls_skipped: 0 blocklisted: false credits_used: 1 error_message: '' started_at: '2024-01-15T10:30:00Z' completed_at: null properties: success: type: boolean example: true description: 'Whether the request was successful.' enum: [] message: type: string example: 'Blocklist check started successfully.' description: 'The message of the response.' enum: [] data: type: object properties: id: type: string example: 01ARZ3NDEKTSV4RRFFQ69G5FAV description: 'The unique identifier for the blocklist check.' enum: [] status: type: string example: pending description: 'The status of the blocklist check. Example: `pending`, `processing`, `completed`, `partially_completed`, `failed`' enum: - pending - processing - completed - partially_completed - failed unique_hosts_checked: type: integer example: 0 description: 'The number of unique hosts checked.' enum: [] total_hosts_detected: type: string example: null description: 'The number of hosts detected.' enum: [] urls_scanned: type: integer example: 0 description: 'The number of URLs scanned.' enum: [] urls_skipped: type: integer example: 0 description: 'The number of URLs skipped.' enum: [] blocklisted: type: boolean example: false description: 'Whether the check is blocklisted.' enum: [] credits_used: type: integer example: 1 description: 'The number of credits used.' enum: [] error_message: type: string example: '' description: 'The error message if the check failed.' enum: [] started_at: type: string example: '2024-01-15T10:30:00Z' description: 'The date and time the check started.' enum: [] completed_at: type: string example: null description: 'The date and time the check completed.' enum: [] required: - id - status - unique_hosts_checked - total_hosts_detected - urls_scanned - urls_skipped - blocklisted - credits_used - error_message - started_at - completed_at required: - success - message tags: - Blocklists requestBody: required: true content: application/json: schema: type: object properties: urls: type: array description: 'Array of URLs to scan (minimum 1 URL, maximum 100 URLs).' example: - 'https://optipub.com' - 'https://postmasterplus.com' items: type: string follow_redirects: type: boolean description: 'optional Whether to follow redirects and scan all hosts in the redirect chain. Defaults to true. When false, only the hosts from the original URLs will be scanned.' example: true required: - urls '/api/v1/blocklist/scan/status/{id}': get: summary: 'Retrieve Blocklist Scan Status.' operationId: retrieveBlocklistScanStatus description: '' parameters: [] responses: 200: description: '' content: application/json: schema: oneOf: - description: '' type: object example: data: id: 01kf105wftsvc42cynh5fcpp5t status: pending unique_hosts_checked: 1 total_hosts_detected: null urls_scanned: 0 urls_skipped: 0 blocklisted: false credits_used: 0 error_message: '' started_at: null completed_at: null success: true message: 'Blocklist check status retrieved successfully.' properties: data: type: object properties: id: type: string example: 01kf105wftsvc42cynh5fcpp5t description: 'The unique identifier for the blocklist check.' enum: [] status: type: string example: pending description: 'The status of the blocklist check. Example: `pending`, `processing`, `completed`, `partially_completed`, `failed`' enum: - pending - processing - completed - partially_completed - failed unique_hosts_checked: type: integer example: 1 description: 'The number of unique hosts checked.' enum: [] total_hosts_detected: type: string example: null description: 'The number of hosts detected.' enum: [] urls_scanned: type: integer example: 0 description: 'The number of URLs scanned.' enum: [] urls_skipped: type: integer example: 0 description: 'The number of URLs skipped.' enum: [] blocklisted: type: boolean example: false description: 'Whether the check is blocklisted.' enum: [] credits_used: type: integer example: 0 description: 'The number of credits used.' enum: [] error_message: type: string example: '' description: 'The error message if the check failed.' enum: [] started_at: type: string example: null description: 'The date and time the check started.' enum: [] completed_at: type: string example: null description: 'The date and time the check completed.' enum: [] required: - id - status - unique_hosts_checked - total_hosts_detected - urls_scanned - urls_skipped - blocklisted - credits_used - error_message - started_at - completed_at success: type: boolean example: true description: 'Whether the request was successful.' enum: [] message: type: string example: 'Blocklist check status retrieved successfully.' description: 'The message of the response.' enum: [] required: - success - message - description: '' type: object example: success: true message: 'Blocklist check status retrieved successfully.' data: id: 01ARZ3NDEKTSV4RRFFQ69G5FAV status: completed unique_hosts_checked: 5 total_hosts_detected: 3 urls_scanned: 2 urls_skipped: 0 blocklisted: true credits_used: 1 error_message: '' started_at: '2024-01-15T10:30:00Z' completed_at: '2024-01-15T10:35:00Z' results: data: - url: 'https://example.com' total_redirects: 2 redirect_urls: - 'https://example.com/redirect1' - 'https://example.com/redirect2' hosts_checked: - host: example.com position: 1 blocklisted: true listed_details: - host: example.com name: 'Spamhaus ZEN' listed: true details: 'Listed on Spamhaus ZEN' properties: success: type: boolean example: true description: 'Whether the request was successful.' enum: [] message: type: string example: 'Blocklist check status retrieved successfully.' description: 'The message of the response.' enum: [] data: type: object properties: id: type: string example: 01ARZ3NDEKTSV4RRFFQ69G5FAV description: 'The unique identifier for the blocklist check.' enum: [] status: type: string example: completed description: 'The status of the blocklist check. Example: `pending`, `processing`, `completed`, `partially_completed`, `failed`' enum: - pending - processing - completed - partially_completed - failed unique_hosts_checked: type: integer example: 5 description: 'The number of unique hosts checked.' enum: [] total_hosts_detected: type: integer example: 3 description: 'The number of hosts detected.' enum: [] urls_scanned: type: integer example: 2 description: 'The number of URLs scanned.' enum: [] urls_skipped: type: integer example: 0 description: 'The number of URLs skipped.' enum: [] blocklisted: type: boolean example: true description: 'Whether the check is blocklisted.' enum: [] credits_used: type: integer example: 1 description: 'The number of credits used.' enum: [] error_message: type: string example: '' description: 'The error message if the check failed.' enum: [] started_at: type: string example: '2024-01-15T10:30:00Z' description: 'The date and time the check started.' enum: [] completed_at: type: string example: '2024-01-15T10:35:00Z' description: 'The date and time the check completed.' enum: [] results: type: object properties: data: type: array example: - url: 'https://example.com' total_redirects: 2 redirect_urls: - 'https://example.com/redirect1' - 'https://example.com/redirect2' hosts_checked: - { host: example.com, position: 1, blocklisted: true, listed_details: [{ host: example.com, name: 'Spamhaus ZEN', listed: true, details: 'Listed on Spamhaus ZEN' }] } description: 'Array of blacklist monitoring history items, each containing URL, redirect information, and blocklist status for each host checked.' enum: [] items: type: object properties: url: type: string example: 'https://example.com' total_redirects: type: integer example: 2 redirect_urls: type: array example: ['https://example.com/redirect1', 'https://example.com/redirect2'] items: { type: string } hosts_checked: type: array example: [{ host: example.com, position: 1, blocklisted: true, listed_details: [{ host: example.com, name: 'Spamhaus ZEN', listed: true, details: 'Listed on Spamhaus ZEN' }] }] items: { type: object, properties: { host: { type: string, example: example.com }, position: { type: integer, example: 1 }, blocklisted: { type: boolean, example: true }, listed_details: { type: array, example: [{ host: example.com, name: 'Spamhaus ZEN', listed: true, details: 'Listed on Spamhaus ZEN' }], items: { type: object, properties: { host: { type: string, example: example.com }, name: { type: string, example: 'Spamhaus ZEN' }, listed: { type: boolean, example: true }, details: { type: string, example: 'Listed on Spamhaus ZEN' } } } } } } required: - data description: 'Detailed results of the blocklist check. Only included when the check is completed and results are requested. Contains a `data` array with monitoring history items.' required: - id - status - unique_hosts_checked - total_hosts_detected - urls_scanned - urls_skipped - blocklisted - credits_used - error_message - started_at - completed_at - results required: - success - message tags: - Blocklists parameters: - in: path name: id description: 'The ULID of the blocklist check.' example: 01ARZ3NDEKTSV4RRFFQ69G5FAV required: true schema: type: string /api/v1/data-sources/report/validity: post: summary: '' operationId: postApiV1DataSourcesReportValidity description: '' parameters: [] responses: { } tags: - Endpoints requestBody: required: true content: application/json: schema: type: object properties: From: type: string description: '' example: consequatur Headers: type: object description: '' example: [] properties: { } Attachments: type: object description: '' example: [] properties: { } ToFull: type: object description: '' example: [] properties: { } required: - From - Headers - Attachments - ToFull /api/v1/screenshot/take: post: summary: 'Take Screenshot.' operationId: takeScreenshot description: 'Take a screenshot of a URL or HTML content.' parameters: [] responses: 200: description: '' content: application/json: schema: oneOf: - description: '' type: object example: data: id: 01kf105wgfgz2prr22zsh0w2et url: 'https://assets.optipub.com/postmaster/screenshots/01kf105wg972sv436a0bdr5v3e/01kf105wgfgz2prr22zsh0w2et.png' format: png width: 1280 height: 600 device_scale: 2 credits_used: 1 started_at: '2026-01-15T00:25:05+00:00' completed_at: '2026-01-15T00:25:12+00:00' created_at: '2026-01-15T14:15:31+00:00' success: true message: 'Screenshot taken successfully.' properties: data: type: object properties: id: type: string example: 01kf105wgfgz2prr22zsh0w2et description: 'The unique identifier for the screenshot.' enum: [] url: type: string example: 'https://assets.optipub.com/postmaster/screenshots/01kf105wg972sv436a0bdr5v3e/01kf105wgfgz2prr22zsh0w2et.png' description: 'The URL of the screenshot image.' enum: [] format: type: string example: png description: 'The format of the screenshot image. Example: `png`, `jpeg`' enum: [] width: type: integer example: 1280 description: 'The width of the screenshot in pixels.' enum: [] height: type: integer example: 600 description: 'The height of the screenshot in pixels.' enum: [] device_scale: type: integer example: 2 description: 'The device scale factor used (1-3). Higher values produce sharper images.' enum: [] credits_used: type: integer example: 1 description: 'The number of credits used for this screenshot.' enum: [] started_at: type: string example: '2026-01-15T00:25:05+00:00' description: 'The date and time when the screenshot capture started.' enum: [] completed_at: type: string example: '2026-01-15T00:25:12+00:00' description: 'The date and time when the screenshot capture completed.' enum: [] created_at: type: string example: '2026-01-15T14:15:31+00:00' description: 'The date and time the screenshot was created.' enum: [] required: - id - url - format - width - height - device_scale - credits_used - started_at - completed_at - created_at success: type: boolean example: true description: 'Whether the request was successful.' enum: [] message: type: string example: 'Screenshot taken successfully.' description: 'The message of the response.' enum: [] required: - success - message - description: '' type: object example: success: true message: 'Screenshot taken successfully.' data: id: 01ARZ3NDEKTSV4RRFFQ69G5FAV url: 'https://assets.optipub.com/postmaster/screenshots/01arz3ndektsv4rrffq69g5fav/01arz3ndektsv4rrffq69g5fav.png' format: png width: 1280 height: 720 credits_used: 1 created_at: '2024-01-15T10:30:00Z' properties: success: type: boolean example: true description: 'Whether the request was successful.' enum: [] message: type: string example: 'Screenshot taken successfully.' description: 'The message of the response.' enum: [] data: type: object properties: id: type: string example: 01ARZ3NDEKTSV4RRFFQ69G5FAV description: 'The unique identifier for the screenshot.' enum: [] url: type: string example: 'https://assets.optipub.com/postmaster/screenshots/01arz3ndektsv4rrffq69g5fav/01arz3ndektsv4rrffq69g5fav.png' description: 'The URL of the screenshot image.' enum: [] format: type: string example: png description: 'The format of the screenshot image. Example: `png`, `jpeg`' enum: [] width: type: integer example: 1280 description: 'The width of the screenshot in pixels.' enum: [] height: type: integer example: 720 description: 'The height of the screenshot in pixels.' enum: [] credits_used: type: integer example: 1 description: 'The number of credits used for this screenshot.' enum: [] created_at: type: string example: '2024-01-15T10:30:00Z' description: 'The date and time the screenshot was created.' enum: [] required: - id - url - format - width - height - credits_used - created_at required: - success - message tags: - Tools requestBody: required: false content: application/json: schema: type: object properties: url: type: string description: 'URL to screenshot (required if html is not provided).' example: '"https://example.com"' nullable: true html: type: string description: 'HTML content to screenshot (required if url is not provided).' example: null nullable: true width: type: integer description: 'optional Viewport width in pixels (320-1920). Defaults to 1280.' example: 1280 nullable: true height: type: integer description: 'optional Viewport height in pixels (240-1080). Defaults to 720.' example: 720 nullable: true format: type: string description: 'optional Image format (png, jpeg, or webp). Defaults to png.' example: '"png"' nullable: true device_scale: type: integer description: 'optional Device scale factor for higher resolution (1-3). Defaults to 1 for retina-quality images.' example: 1 nullable: true /api/v1/screenshots: get: summary: 'List Screenshots.' operationId: listScreenshots description: 'Retrieve a paginated list of screenshots for the current team.' parameters: - in: query name: per_page description: 'The number of screenshots per page (1-100). Defaults to 15.' example: 15 required: false schema: type: integer description: 'The number of screenshots per page (1-100). Defaults to 15.' example: 15 - in: query name: page description: 'The page number.' example: 1 required: false schema: type: integer description: 'The page number.' example: 1 - in: query name: sort description: 'Sort order. Use `-` prefix for descending. Options: `created_at`, `-created_at`, `format`, `-format`. Defaults to `-created_at`.' example: '-created_at' required: false schema: type: string description: 'Sort order. Use `-` prefix for descending. Options: `created_at`, `-created_at`, `format`, `-format`. Defaults to `-created_at`.' example: '-created_at' responses: 200: description: '' content: application/json: schema: type: object example: success: true message: 'Screenshots retrieved successfully.' data: - id: 01ARZ3NDEKTSV4RRFFQ69G5FAV url: 'https://assets.optipub.com/postmaster/screenshots/01arz3ndektsv4rrffq69g5fav/01arz3ndektsv4rrffq69g5fav.png' format: png width: 1280 height: 720 credits_used: 1 created_at: '2024-01-15T10:30:00Z' meta: current_page: 1 from: 1 last_page: 5 per_page: 15 to: 15 total: 75 properties: success: type: boolean example: true message: type: string example: 'Screenshots retrieved successfully.' data: type: array example: - id: 01ARZ3NDEKTSV4RRFFQ69G5FAV url: 'https://assets.optipub.com/postmaster/screenshots/01arz3ndektsv4rrffq69g5fav/01arz3ndektsv4rrffq69g5fav.png' format: png width: 1280 height: 720 credits_used: 1 created_at: '2024-01-15T10:30:00Z' items: type: object properties: id: type: string example: 01ARZ3NDEKTSV4RRFFQ69G5FAV url: type: string example: 'https://assets.optipub.com/postmaster/screenshots/01arz3ndektsv4rrffq69g5fav/01arz3ndektsv4rrffq69g5fav.png' format: type: string example: png width: type: integer example: 1280 height: type: integer example: 720 credits_used: type: integer example: 1 created_at: type: string example: '2024-01-15T10:30:00Z' meta: type: object properties: current_page: type: integer example: 1 from: type: integer example: 1 last_page: type: integer example: 5 per_page: type: integer example: 15 to: type: integer example: 15 total: type: integer example: 75 tags: - Tools requestBody: required: false content: application/json: schema: type: object properties: per_page: type: integer description: 'Must be at least 1. Must not be greater than 100.' example: 21 page: type: integer description: 'Must be at least 1.' example: 45 sort: type: string description: '' example: format enum: - created_at - '-created_at' - format - '-format' '/api/v1/screenshot/{id}': get: summary: 'Get Screenshot.' operationId: getScreenshot description: 'Retrieve details of a specific screenshot by its ID.' parameters: [] responses: 200: description: '' content: application/json: schema: oneOf: - description: '' type: object example: data: id: 01kf105whhh0nkv1tcezv8k8gf url: 'https://assets.optipub.com/postmaster/screenshots/01kf105wh8yw9c0k5tjded09ft/01kf105whhh0nkv1tcezv8k8gf.jpg' format: jpeg width: 1280 height: 1080 device_scale: 1 credits_used: 1 started_at: '2025-12-31T08:41:42+00:00' completed_at: '2025-12-31T08:41:52+00:00' created_at: '2026-01-15T14:15:31+00:00' success: true message: 'Screenshot retrieved successfully.' properties: data: type: object properties: id: type: string example: 01kf105whhh0nkv1tcezv8k8gf description: 'The unique identifier for the screenshot.' enum: [] url: type: string example: 'https://assets.optipub.com/postmaster/screenshots/01kf105wh8yw9c0k5tjded09ft/01kf105whhh0nkv1tcezv8k8gf.jpg' description: 'The URL of the screenshot image.' enum: [] format: type: string example: jpeg description: 'The format of the screenshot image. Example: `png`, `jpeg`' enum: [] width: type: integer example: 1280 description: 'The width of the screenshot in pixels.' enum: [] height: type: integer example: 1080 description: 'The height of the screenshot in pixels.' enum: [] device_scale: type: integer example: 1 description: 'The device scale factor used (1-3). Higher values produce sharper images.' enum: [] credits_used: type: integer example: 1 description: 'The number of credits used for this screenshot.' enum: [] started_at: type: string example: '2025-12-31T08:41:42+00:00' description: 'The date and time when the screenshot capture started.' enum: [] completed_at: type: string example: '2025-12-31T08:41:52+00:00' description: 'The date and time when the screenshot capture completed.' enum: [] created_at: type: string example: '2026-01-15T14:15:31+00:00' description: 'The date and time the screenshot was created.' enum: [] required: - id - url - format - width - height - device_scale - credits_used - started_at - completed_at - created_at success: type: boolean example: true description: 'Whether the request was successful.' enum: [] message: type: string example: 'Screenshot retrieved successfully.' description: 'The message of the response.' enum: [] required: - success - message - description: '' type: object example: success: true message: 'Screenshot retrieved successfully.' data: id: 01ARZ3NDEKTSV4RRFFQ69G5FAV url: 'https://assets.optipub.com/postmaster/screenshots/01arz3ndektsv4rrffq69g5fav/01arz3ndektsv4rrffq69g5fav.png' format: png width: 1280 height: 720 credits_used: 1 created_at: '2024-01-15T10:30:00Z' properties: success: type: boolean example: true description: 'Whether the request was successful.' enum: [] message: type: string example: 'Screenshot retrieved successfully.' description: 'The message of the response.' enum: [] data: type: object properties: id: type: string example: 01ARZ3NDEKTSV4RRFFQ69G5FAV description: 'The unique identifier for the screenshot.' enum: [] url: type: string example: 'https://assets.optipub.com/postmaster/screenshots/01arz3ndektsv4rrffq69g5fav/01arz3ndektsv4rrffq69g5fav.png' description: 'The URL of the screenshot image.' enum: [] format: type: string example: png description: 'The format of the screenshot image. Example: `png`, `jpeg`' enum: [] width: type: integer example: 1280 description: 'The width of the screenshot in pixels.' enum: [] height: type: integer example: 720 description: 'The height of the screenshot in pixels.' enum: [] credits_used: type: integer example: 1 description: 'The number of credits used for this screenshot.' enum: [] created_at: type: string example: '2024-01-15T10:30:00Z' description: 'The date and time the screenshot was created.' enum: [] required: - id - url - format - width - height - credits_used - created_at required: - success - message tags: - Tools parameters: - in: path name: id description: 'The ULID of the screenshot.' example: 01ARZ3NDEKTSV4RRFFQ69G5FAV required: true schema: type: string