Valimail

Valimail Users API

The Users API from Valimail — 4 operation(s) for users.

GitHub OpenAPI

Operations 7

GET /accounts/{slug}/users Returns users linked to the account slug provided.
POST /accounts/{slug}/users Creates a new user linked to the account slug provided and sends an invitation email.
POST /accounts/{slug}/users/{user-slug}/invitation Sends a new invitation email for the existing user and returns the latest activation link.
GET /accounts/{slug}/users/{user-slug} Returns account user data by account slug and user slug.
PUT /accounts/{slug}/users/{user-slug} Updates user data by account slug and user slug.
DELETE /accounts/{slug}/users/{user-slug} Inactivates a user according to the account slug and user slug provided.
DELETE /accounts/{slug}/v2/users/{user-slug} Inactivates a user according to the account slug and user slug provided.

Documentation

📖
APIReference
https://api.valimail.com/docs/config.html
📖
APIReference
https://api.valimail.com/docs/account.html

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/valimail/refs/heads/main/openapi/valimail-users-api-openapi.yml

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/valimail-users-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no email required.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

valimail-users-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Valimail Users API
  version: 1.0.0
  description: 'Operations tagged Users across 2 of this provider''s published API definitions: valimail-account-openapi-original.yml, valimail-partner-openapi-original.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.valimail.com
  description: API services
- url: https://api.valimail-staging.com
  description: Stage test server
- url: http://localhost:7001
  description: Local development server
security:
- bearerAuth: []
tags:
- name: Users
paths:
  /accounts/{slug}/users:
    get:
      summary: Returns users linked to the account slug provided.
      tags:
      - Users
      parameters:
      - name: slug
        in: path
        description: Filter by Account slug.
        required: true
        schema:
          type: string
        example: valimail
      - name: email
        in: query
        description: Filter by List of emails.
        schema:
          type: array
          items:
            type: string
        example:
        - test@email.com
        - anothertest@email.com
      - name: first-name
        in: query
        description: Filter by List of First Names.
        schema:
          type: array
          items:
            type: string
        example:
        - John
        - Jane
      - name: last-name
        in: query
        description: Filter by List of Last Names.
        schema:
          type: array
          items:
            type: string
        example:
        - Doe
        - Smith
      - name: user-slug
        in: query
        description: Filter by List of User slugs.
        schema:
          type: array
          items:
            type: string
        example:
        - john-doe
        - jane-smith
      - name: has-accepted-invitation
        in: query
        description: Boolean flag. Use true to return users whose invitation has already been accepted, and false to return users whose invitation has not been accepted.
        schema:
          type: boolean
        example: true
      - name: user-type
        in: query
        description: Filter by List of user types.
        schema:
          type: array
          items:
            type: string
            enum:
            - member
            - owner
            - marketer
        example:
        - owner
        - marketer
      - name: reverse
        in: query
        description: Reverse the order of the list to be provided.
        schema:
          type: boolean
        example: false
      - name: sort-key
        in: query
        description: 'Sorts the given list by a key. Allowed values: slug, email, first_name, last_name, account_slug, last_active_at, user_type.'
        schema:
          type: string
        example: email
      - name: page
        in: query
        description: Page to be accessed according to the division of items provided in conjunction with the 'per-page' parameter.
        schema:
          type: integer
        example: 1
      - name: per-page
        in: query
        description: Number of users per page on the provided list.
        schema:
          type: integer
        example: 100
      responses:
        '200':
          description: OK - List of the Users linked to the account slug are provided
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '400':
          description: Bad Request - Invalid input data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationResponse'
        '401':
          description: Unauthorized - Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - Authorization failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable Entity - Failed to normalize or parse
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Over Rate - Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error - Service, database, or unclassified error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      summary: Creates a new user linked to the account slug provided and sends an invitation email.
      tags:
      - Users
      parameters:
      - name: slug
        in: path
        description: Account slug to create an user.
        required: true
        schema:
          type: string
        example: valimail
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUser'
      responses:
        '200':
          description: Ok - New user created and invitation generated. The response includes the activation link that was generated for the invitation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvitedUser'
        '400':
          description: Bad Request - Invalid input data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationResponse'
        '401':
          description: Unauthorized - Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - Authorization failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable Entity - Failed to normalize or parse
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Over Rate - Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error - Service, database, or unclassified error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    servers:
    - url: https://api.valimail.com
      description: API services
    - url: https://api.valimail-staging.com
      description: Stage test server
    - url: http://localhost:7001
      description: Local development server
  /accounts/{slug}/users/{user-slug}/invitation:
    post:
      summary: Sends a new invitation email for the existing user and returns the latest activation link.
      description: If the user has already accepted the invitation, the response returns invitation-accepted-at and an empty activation-link.
      tags:
      - Users
      parameters:
      - name: slug
        in: path
        description: Account slug to find the user.
        required: true
        schema:
          type: string
        example: valimail
      - name: user-slug
        in: path
        description: User slug to receive a new invitation.
        required: true
        schema:
          type: string
        example: john-doe
      responses:
        '200':
          description: Ok - Invitation email processed. The response includes the latest activation link, or invitation-accepted-at with an empty activation-link when the invitation has already been accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvitedUser'
              examples:
                success-invitation-resend:
                  summary: Invitation resent successfully
                  value:
                    email: test@234.com
                    first-name: John
                    last-name: Doe
                    slug: john-doe
                    account-slug: valimail
                    last-active-at: '2026-02-24T12:30:00Z'
                    user-type: owner
                    activation-link: https://app.valimail.com/users/invitation/accept?invitation_token=example-token
                invitation-already-accepted:
                  summary: User already accepted the invitation
                  value:
                    email: test@234.com
                    first-name: John
                    last-name: Doe
                    slug: john-doe
                    account-slug: valimail
                    last-active-at: '2026-02-24T12:30:00Z'
                    invitation-accepted-at: '2026-04-07T09:15:00Z'
                    user-type: owner
                    activation-link: ''
        '400':
          description: Bad Request - Invalid input data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationResponse'
        '401':
          description: Unauthorized - Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - Authorization failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found - Account or user not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultDelegatedAPIErrorResponse'
        '422':
          description: Unprocessable Entity - Failed to normalize or parse
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Over Rate - Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error - Service, database, or unclassified error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    servers:
    - url: https://api.valimail.com
      description: API services
    - url: https://api.valimail-staging.com
      description: Stage test server
    - url: http://localhost:7001
      description: Local development server
  /accounts/{slug}/users/{user-slug}:
    get:
      summary: Returns account user data by account slug and user slug.
      tags:
      - Users
      parameters:
      - name: slug
        in: path
        description: Account slug to be queried.
        required: true
        schema:
          type: string
        example: valimail
      - name: user-slug
        in: path
        description: User slug to be queried.
        required: true
        schema:
          type: string
        example: john-doe
      responses:
        '200':
          description: Ok - Single User is provided (response fields will appear according to the existing data)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Bad Request - Invalid input data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationResponse'
        '401':
          description: Unauthorized - Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - Authorization failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found - Account or user not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable Entity - Failed to normalize or parse
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Over Rate - Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error - Service, database, or unclassified error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      summary: Updates user data by account slug and user slug.
      tags:
      - Users
      parameters:
      - name: slug
        in: path
        description: Account slug to update an user.
        required: true
        schema:
          type: string
        example: valimail
      - name: user-slug
        in: path
        description: User slug to be updated.
        required: true
        schema:
          type: string
        example: john-doe
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserUpdate'
      responses:
        '200':
          description: Ok - User Updated (response fields will appear according to the existing data)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Bad Request - Invalid input data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationResponse'
        '401':
          description: Unauthorized - Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - Authorization failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found - Account or user not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable Entity - Failed to normalize or parse
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Over Rate - Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error - Service, database, or unclassified error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      summary: Inactivates a user according to the account slug and user slug provided.
      tags:
      - Users
      parameters:
      - name: slug
        in: path
        description: Account slug to be queried.
        required: true
        schema:
          type: string
        example: valimail
      - name: user-slug
        in: path
        description: User slug to be queried.
        required: true
        schema:
          type: string
        example: john-doe
      responses:
        '200':
          description: deleted user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserDelete'
        '400':
          description: Bad Request - Invalid input data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationResponse'
        '401':
          description: Unauthorized - Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - Authorization failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable Entity - Failed to normalize or parse
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Over Rate - Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error - Service, database, or unclassified error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    servers:
    - url: https://api.valimail.com
      description: API services
    - url: https://api.valimail-staging.com
      description: Stage test server
    - url: http://localhost:7001
      description: Local development server
  /accounts/{slug}/v2/users/{user-slug}:
    delete:
      summary: Inactivates a user according to the account slug and user slug provided.
      tags:
      - Users
      parameters:
      - name: slug
        in: path
        description: Account slug to be queried.
        required: true
        schema:
          type: string
        example: valimail
      - name: user-slug
        in: path
        description: User slug to be queried.
        required: true
        schema:
          type: string
        example: john-doe
      responses:
        '200':
          description: deleted user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserDelete'
        '400':
          description: Bad Request - Invalid input data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationResponse'
        '401':
          description: Unauthorized - Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - Authorization failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable Entity - Failed to normalize or parse
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Over Rate - Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error - Service, database, or unclassified error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    servers:
    - url: https://api.valimail.com
      description: API services
    - url: https://api.valimail-staging.com
      description: Stage test server
    - url: http://localhost:7001
      description: Local development server
components:
  schemas:
    CreateUser:
      type: object
      properties:
        email:
          description: Email of the user.
          type: string
        first-name:
          description: First name of the user.
          type: string
        last-name:
          description: Last name of the user.
          type: string
        user-type:
          description: 'Optional: User type in the account. Defaults to owner. Marketer is only valid when the account supports that role.'
          type: string
          enum:
          - member
          - owner
          - marketer
    UserDelete:
      type: object
      properties:
        slug:
          type: string
        account-slug:
          type: string
    User:
      type: object
      properties:
        email:
          type: string
        first-name:
          type: string
        last-name:
          type: string
        slug:
          type: string
        account-slug:
          type: string
        last-active-at:
          type: string
          format: date-time
        invitation-accepted-at:
          type: string
          format: date-time
          description: Present when the invitation has already been accepted.
        user-type:
          type: string
          enum:
          - member
          - owner
          - marketer
      example:
        email: test@234.com
        first-name: John
        last-name: Doe
        slug: john-doe
        account-slug: valimail
        last-active-at: '2026-02-24T12:30:00Z'
        invitation-accepted-at: '2026-04-07T09:15:00Z'
        user-type: owner
    ValidationResponse:
      type: object
      properties:
        params:
          type: string
        detail:
          type: array
          items:
            $ref: '#/components/schemas/ValidationDetail'
    ErrorResponse:
      type: object
      properties:
        request:
          type: string
        message:
          type: string
        type:
          type: string
        request-id:
          type: string
        call:
          type: string
    UserUpdate:
      type: object
      properties:
        email:
          type: string
        first-name:
          type: string
        last-name:
          type: string
        user-type:
          type: string
          enum:
          - member
          - owner
          - marketer
    ValidationDetail:
      type: object
      properties:
        field:
          type: string
        value:
          type: string
        message:
          type: string
    DefaultDelegatedAPIErrorResponse:
      type: object
      properties:
        request:
          type: string
        message:
          type: string
        type:
          type: string
        call:
          type: string
    InvitedUser:
      allOf:
      - $ref: '#/components/schemas/User'
      - type: object
        properties:
          activation-link:
            type: string
            description: Invitation activation URL. Returned as an empty string when the invitation has already been accepted and invitation-accepted-at is present in the response.
      example:
        email: test@234.com
        first-name: John
        last-name: Doe
        slug: john-doe
        account-slug: valimail
        last-active-at: '2026-02-24T12:30:00Z'
        user-type: owner
        activation-link: https://app.valimail.com/users/invitation/accept?invitation_token=example-token
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
x-refined-from:
- valimail-account-openapi-original.yml
- valimail-partner-openapi-original.yml