sendly-now Validation API

openapi: 3.2.0
info:
  title: Sendly Now Validation API
  version: 1.0.0
  contact:
    name: Sendly Support
    url: https://sendly.now
  license:
    name: AGPL-3.0
    url: https://www.gnu.org/licenses/agpl-3.0.txt
  description: 'Operations tagged Validation across 2 of this provider''s published API definitions: openapi.json, sendly-now-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.sendly.now
tags:
- description: 'Bulk email validation, billed per address: a bounded synchronous batch, and background runs over a whole list. Distinct from `Verify`, which is the one open, unauthenticated, single-address endpoint the marketing site calls.'
  name: Validation
paths:
  /api/v1/email-validations:
    post:
      description: 'Check up to 50 addresses for whether they can receive mail, and for the signals that make one worth mailing. Billed per address.


        The response publishes a `verdict` alongside the flags it was drawn from. Branch on the verdict: the two obvious readings of the flags are both wrong — a free-provider address (`is_personal`) and a role mailbox (`is_role_address`) are ordinary, deliverable addresses that real customers use, and refusing them would shrink a list for no reason. `is_disposable` is the only flag that lowers a verdict.


        `unknown` means DNS did not answer in time, so that address was NOT checked. It is a separate value from `undeliverable` on purpose — acting on the two together deletes live contacts over a network hiccup.


        The 50-address ceiling is a latency bound, not a payload one: every distinct DOMAIN in the batch costs a DNS round trip. To validate a whole list, use `POST /api/v1/lists/{id}/validation-runs`, which runs as a background job.


        Requires the `validation:write` scope — Check whether email addresses can receive mail — this is billed per address.'
      operationId: v1ValidateEmails
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailValidationBatchRequestV1'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailValidationBatchV1'
          description: One verdict per address, in the order they were given
        '401':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
          description: '`invalid_api_key` or `invalid_session` — missing or invalid credentials.'
        '403':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
          description: '`scope_missing`, `project_access_denied`, or `project_disabled`.'
        '422':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
          description: '`validation_error` — query, path, or body parameters did not match the schema.'
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
          description: '`rate_limited` — see `Retry-After` and the `RateLimit` headers.'
        '500':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
          description: '`internal_error`.'
      security:
      - ApiKeyAuth: []
      - SessionAuth: []
      - OAuth2:
        - validation:write
      summary: Validate a batch of email addresses
      tags:
      - Validation
    servers:
    - url: https://api.sendly.now
  /api/v1/lists/{id}/validation-runs:
    post:
      description: 'Start a background run over every contact on the list and answer immediately with the run. Poll `GET /api/v1/validation-runs/{id}` for progress and read the verdicts from its `/results` page.


        This VALIDATES and changes nothing: no membership is unsubscribed, no contact is deleted. What to do about an `undeliverable` address is your decision, and a run that acted on its own findings would be acting on a DNS lookup that can also answer `unknown`.


        A second run while one is already in flight for the same list is refused with 409 rather than queued: two runs would bill the same addresses twice.


        Requires the `validation:write` scope — Check whether email addresses can receive mail — this is billed per address.'
      operationId: v1StartListValidationRun
      parameters:
      - description: Resource id.
        in: path
        name: id
        required: true
        schema:
          description: Resource id.
          format: uuid
          type: string
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailValidationRunV1'
          description: The run, accepted and queued
        '401':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
          description: '`invalid_api_key` or `invalid_session` — missing or invalid credentials.'
        '403':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
          description: '`scope_missing`, `project_access_denied`, or `project_disabled`.'
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
          description: '`resource_not_found` — no list with this id belongs to the authenticated project.'
        '422':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
          description: '`validation_error` — query, path, or body parameters did not match the schema.'
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
          description: '`rate_limited` — see `Retry-After` and the `RateLimit` headers.'
        '500':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
          description: '`internal_error`.'
      security:
      - ApiKeyAuth: []
      - SessionAuth: []
      - OAuth2:
        - validation:write
      summary: Validate every address on a list
      tags:
      - Validation
    servers:
    - url: https://api.sendly.now
  /api/v1/validation-runs/{id}:
    get:
      description: 'How far a run has got and what it found. The counters are advanced by each batch in the same step that commits the rows they count, so they are a ledger rather than a cached estimate and may be branched on.


        There is no total to divide by, deliberately: a list changes size while a run walks it, so a denominator captured when the run started would be wrong by the time you read it. A run is finished when `status` is `completed` or `failed`, never when a percentage reaches 100.


        Requires the `validation:read` scope — View your email validation runs and their results.'
      operationId: v1GetValidationRun
      parameters:
      - description: Resource id.
        in: path
        name: id
        required: true
        schema:
          description: Resource id.
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailValidationRunV1'
          description: The run
        '401':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
          description: '`invalid_api_key` or `invalid_session` — missing or invalid credentials.'
        '403':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
          description: '`scope_missing`, `project_access_denied`, or `project_disabled`.'
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
          description: '`resource_not_found` — no validation run with this id belongs to the authenticated project.'
        '422':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
          description: '`validation_error` — query, path, or body parameters did not match the schema.'
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
          description: '`rate_limited` — see `Retry-After` and the `RateLimit` headers.'
        '500':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
          description: '`internal_error`.'
      security:
      - ApiKeyAuth: []
      - SessionAuth: []
      - OAuth2:
        - validation:read
      summary: Retrieve a validation run
      tags:
      - Validation
    servers:
    - url: https://api.sendly.now
  /api/v1/validation-runs/{id}/results:
    get:
      description: 'One page of a run''s verdicts, cursor-paginated. Filter with `verdict` — `undeliverable` is the page you want when you are about to act on the results.


        No total is reported: a run over a large list holds millions of rows, and counting them on every page read is the query this design exists to avoid. The run''s own counters carry the numbers worth having.


        `contact_id` is the contact the address belonged to when it was checked, and it is null for a contact deleted since. The `email` is stored on the result rather than read through the contact, so a completed run reports what it actually checked even after the contact changed address.


        Requires the `validation:read` scope — View your email validation runs and their results.'
      operationId: v1ListValidationRunResults
      parameters:
      - description: Resource id.
        in: path
        name: id
        required: true
        schema:
          description: Resource id.
          format: uuid
          type: string
      - in: query
        name: limit
        required: false
        schema:
          default: 50
          maximum: 200
          minimum: 1
          type: integer
      - description: Opaque cursor from a previous response's `next_cursor`.
        in: query
        name: after
        required: false
        schema:
          description: Opaque cursor from a previous response's `next_cursor`.
          minLength: 1
          type: string
      - description: Return only results with this verdict — `undeliverable` is the usual filter.
        in: query
        name: verdict
        required: false
        schema:
          allOf:
          - $ref: '#/components/schemas/EmailValidationVerdictV1'
          - description: Return only results with this verdict — `undeliverable` is the usual filter.
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailValidationResultListV1'
          description: One page of results
        '401':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
          description: '`invalid_api_key` or `invalid_session` — missing or invalid credentials.'
        '403':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
          description: '`scope_missing`, `project_access_denied`, or `project_disabled`.'
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
          description: '`resource_not_found` — no validation run with this id belongs to the authenticated project.'
        '422':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
          description: '`validation_error` — query, path, or body parameters did not match the schema.'
        '429':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
          description: '`rate_limited` — see `Retry-After` and the `RateLimit` headers.'
        '500':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
          description: '`internal_error`.'
      security:
      - ApiKeyAuth: []
      - SessionAuth: []
      - OAuth2:
        - validation:read
      summary: List a validation run's results
      tags:
      - Validation
    servers:
    - url: https://api.sendly.now
components:
  schemas:
    EmailValidationVerdictV1:
      description: '`deliverable`: the domain resolves and accepts mail, with no badness signal. `undeliverable`: the domain does not exist or publishes no MX records. `risky`: deliverable, but a throwaway-inbox provider — mailing it costs sender reputation. `unknown`: DNS did not answer in time, so this address was NOT checked. Ask again; never delete a contact on `unknown`.'
      enum:
      - deliverable
      - undeliverable
      - risky
      - unknown
      type: string
    EmailValidationBatchV1:
      description: One verdict per address, in the order they were given.
      properties:
        results:
          items:
            $ref: '#/components/schemas/EmailValidationV1'
          type: array
      required:
      - results
      type: object
    Problem:
      description: RFC 9457 problem document, served as `application/problem+json`. Returned by every 4xx/5xx response on the `/api/v1` surface.
      properties:
        code:
          description: Machine-readable lowercase error code, e.g. `scope_missing`.
          type: string
        detail:
          description: Explanation specific to this occurrence.
          type: string
        errors:
          description: Field-level failures. Present on 422 `validation_error` responses.
          items:
            properties:
              code:
                type: string
              message:
                type: string
              pointer:
                description: RFC 6901 JSON Pointer to the offending field.
                type: string
            required:
            - pointer
            - code
            - message
            type: object
          type: array
        instance:
          description: Request path the failure occurred on.
          type: string
        next:
          description: The tool an agent calls next to repair this failure — `request_scopes` for a missing permission, `upgrade_plan` for an exhausted plan. Absent when no tool repairs it.
          properties:
            args:
              additionalProperties: {}
              description: Arguments to call it with.
              type: object
            tool:
              description: The MCP tool that repairs this failure, e.g. `upgrade_plan`.
              type: string
          required:
          - tool
          type: object
        request_id:
          description: Correlation id — quote it in support requests.
          type: string
        status:
          description: HTTP status code, repeated in the body.
          type: integer
        title:
          description: Short, stable summary — the same for every occurrence of a `type`.
          type: string
        type:
          description: Dereferenceable URI identifying the error class, anchored on the docs errors page.
          format: uri
          type: string
      required:
      - type
      - title
      - status
      - code
      type: object
    EmailValidationRunV1:
      description: One bulk validation run over a list.
      properties:
        completed_at:
          format: date-time
          type:
          - string
          - 'null'
        created_at:
          format: date-time
          type: string
        deliverable_count:
          type: integer
        failure_reason:
          description: Set only on `failed`. Prose for an operator; never parse it.
          type:
          - string
          - 'null'
        id:
          type: string
        list_id:
          type:
          - string
          - 'null'
        processed_count:
          description: 'Addresses checked so far. There is deliberately no total: a list changes size while a run walks it, so a denominator captured up front would be wrong by the time you read it.'
          type: integer
        risky_count:
          type: integer
        started_at:
          format: date-time
          type:
          - string
          - 'null'
        status:
          enum:
          - pending
          - running
          - completed
          - failed
          type: string
        undeliverable_count:
          type: integer
      required:
      - id
      - list_id
      - status
      - processed_count
      - deliverable_count
      - undeliverable_count
      - risky_count
      - started_at
      - completed_at
      - failure_reason
      - created_at
      type: object
    EmailValidationV1:
      description: One address's verdict, with the evidence behind it.
      properties:
        email:
          type: string
        has_mx_records:
          description: The domain publishes MX records.
          type: boolean
        is_disposable:
          description: A throwaway-inbox provider. The ONLY flag here that lowers the verdict.
          type: boolean
        is_personal:
          description: A free/consumer provider (Gmail, Outlook). List-quality information, not a problem.
          type: boolean
        is_role_address:
          description: 'The local part addresses a role (`support@`, `info@`), not a person. List-quality information: role mailboxes are deliverable and companies answer them.'
          type: boolean
        reasons:
          description: Human-readable findings. Prose for a person to read — branch on `verdict`, never on these.
          items:
            type: string
          type: array
        verdict:
          $ref: '#/components/schemas/EmailValidationVerdictV1'
      required:
      - email
      - verdict
      - is_disposable
      - is_role_address
      - is_personal
      - has_mx_records
      - reasons
      type: object
    EmailValidationBatchRequestV1:
      properties:
        emails:
          description: The addresses to check, at most 50. Every distinct DOMAIN costs a DNS round trip, so this endpoint is bounded by latency rather than payload size — validate a whole list with `POST /api/v1/lists/{id}/validation-runs`, which is a background job.
          items:
            format: email
            type: string
          maxItems: 50
          minItems: 1
          type: array
      required:
      - emails
      type: object
    EmailValidationResultListV1:
      description: One page of a run's results. No total — a run over a large list holds millions of rows, and the run's own counters are the numbers worth reading.
      properties:
        data:
          items:
            allOf:
            - $ref: '#/components/schemas/EmailValidationV1'
            - properties:
                contact_id:
                  type:
                  - string
                  - 'null'
              required:
              - contact_id
              type: object
            description: One address's verdict, with the evidence behind it.
          type: array
        has_more:
          type: boolean
        next_cursor:
          description: Pass as `after` to fetch the next page. `null` on the last page.
          type:
          - string
          - 'null'
      required:
      - data
      - has_more
      - next_cursor
      type: object
  securitySchemes:
    ApiKeyAuth:
      bearerFormat: API Key
      description: 'API key authentication. Use a `sk_*` (FULL) or `pk_*` (SENDING_ONLY) key as the bearer token. Public keys (`pk_*`) are restricted to the email-send endpoints and the self-serve list subscribe/unsubscribe pair; every other endpoint — event tracking included — answers 403 for them. In scope terms (used by `/api/v1/*` operations): FULL keys hold every scope; SENDING_ONLY keys hold only `emails:send`.'
      scheme: bearer
      type: http
    MailgunBasicAuth:
      description: 'Mailgun-style authentication for the `/api/compat/mailgun/*` operations only: HTTP Basic with the username `api` and a Sendly API key (`sk_*`, or a `pk_*` send-only key) as the password, exactly as mailgun.js sends it.'
      scheme: basic
      type: http
    OAuth2:
      description: 'OAuth 2.1 with PKCE, for AI agents and other delegated clients (this is what the MCP endpoint at `/api/mcp` uses, and how a third-party application sends on a user''s behalf). Tokens are minted through the consent screen and carry ONLY the scopes the user ticked there, so an operation lists the single scope it requires and a token without it answers `403` with code `SCOPE_MISSING` — before any input is parsed. Unlike an API key, a delegated token reaches an operation only where the route itself declares a scope; every other route refuses it outright.


        **Ask for the right audience.** Pass `resource=https://app.sendly.now/api` on the authorization AND the token request to receive a token for this REST API; `resource=https://app.sendly.now/api/mcp` is the MCP endpoint''s identifier. A request carrying no `resource` receives an OPAQUE token, which every endpoint here rejects. Each identifier publishes RFC 9728 metadata at `/.well-known/oauth-protected-resource/api` and `/.well-known/oauth-protected-resource/api/mcp`.


        **Name the project on every call.** An OAuth grant belongs to a USER, not to a project — the same person may belong to several — so a delegated token carries no tenant and the project is chosen per request with the `x-project-id` header, checked against real membership. Omit it and a project-scoped operation answers `400`; send one the user does not belong to and it answers `403 PROJECT_ACCESS_DENIED`. List the projects a token may name with `GET /api/users/me/projects` (scope `projects:read`), which needs no header. API keys are unaffected: a key already names its project.'
      flows:
        authorizationCode:
          authorizationUrl: https://app.sendly.now/api/auth/oauth2/authorize
          refreshUrl: https://app.sendly.now/api/auth/oauth2/token
          scopes:
            account:read: See your profile and notification preferences
            account:write: Edit your profile and preferences, export your data, delete your account
            analytics:read: View your sending analytics and engagement metrics
            api-keys:read: See which API keys exist, including what each one is allowed to do
            api-keys:write: Create, rotate, and revoke API keys — these keep working even after you disconnect this app
            billing:read: See your plan, usage, invoices and spending limits
            billing:write: Start a checkout, change spending limits, open the billing portal, cancel or refund
            campaigns:read: View your campaigns and their performance
            campaigns:send: Send or schedule your campaigns to their audience
            campaigns:write: Create, edit, and organize your campaigns
            connections:read: See connected services such as Slack and connected AI apps
            connections:write: Connect, re-verify and disconnect services
            contacts:read: View your contacts and their custom fields
            contacts:write: Create, update, and delete your contacts
            deliverability:read: Check why mail from one of your domains is not arriving
            domains:read: View your sending domains and their verification status
            domains:write: Add and remove sending domains, and trigger verification
            emails:read: View the emails you have sent and their delivery status
            emails:send: Send emails from your verified domains
            emails:test: Send test emails to your own address from the Sendly sandbox
            events:read: View the custom events your application has recorded
            events:write: Record custom events for your contacts
            lists:read: View your subscriber lists and who is on them
            lists:write: Create, rename, and delete your subscriber lists
            mailbox-conversations:read: Read the conversations in your hosted mailboxes — every message and attachment people have sent you
            mailbox-conversations:reply: Reply to conversations in your hosted mailboxes, from the mailbox's own address
            mailboxes:read: View the mailboxes on your domains and their settings
            mailboxes:send: Write and send new email from your hosted mailboxes, as that address
            mailboxes:write: Create and delete mailboxes on your verified domains
            members:read: See who belongs to your projects
            members:write: Add and remove project members and change their roles
            projects:read: View your projects and their settings
            projects:write: Create, change, reset and delete projects on your account
            segments:read: View your segments and who belongs to them
            segments:write: Create, edit, and delete your segments
            support:read: See your support tickets
            support:write: Open support tickets and suspension appeals
            suppression:read: View the addresses on your suppression list
            suppression:write: Add and remove addresses on your suppression list
            templates:read: View your email templates
            templates:write: Create, edit, and delete your email templates
            topics:read: View the topics you mail about and who is subscribed to each
            topics:write: Create and edit topics, and change what your contacts are subscribed to — this decides who your campaigns reach
            usage:read: View your usage totals and billing limits
            validation:read: View your email validation runs and their results
            validation:write: Check whether email addresses can receive mail — this is billed per address
            webhooks:read: View your webhook endpoints and their delivery history
            webhooks:write: Create, edit, and delete your webhook endpoints
            workflows:read: View your automation workflows and their runs
            workflows:write: Create, edit, enable, and delete your automation workflows
          tokenUrl: https://app.sendly.now/api/auth/oauth2/token
      type: oauth2
    PostmarkServerToken:
      description: 'Postmark-style authentication for the `/api/compat/postmark/*` operations only: a Sendly API key (`sk_*`, or a `pk_*` send-only key) sent in the `X-Postmark-Server-Token` header, exactly where the postmark SDK puts its server token.'
      in: header
      name: X-Postmark-Server-Token
      type: apiKey
    SessionAuth:
      description: BetterAuth session cookie. Used by the dashboard / browser clients. When present, the active project is taken from the `x-project-id` header.
      in: cookie
      name: better-auth.session_token
      type: apiKey
x-refined-from:
- openapi.json
- sendly-now-openapi.json