> ## Documentation Index
> Fetch the complete documentation index at: https://docs.railmail.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a custom field

> Creates a custom field definition. SELECT and MULTI_SELECT require `options`. Requires scope: `custom_fields:write`. Tenancy: scoped to the API key's project.



## OpenAPI

````yaml /api-reference/openapi.json post /api/v1/custom-fields
openapi: 3.1.0
info:
  title: Railmail Public API
  version: v1
  description: >-
    REST API for managing the Railmail email marketing platform
    programmatically.


    ## Authentication

    Every request must carry a project-scoped API key, either in the `X-API-Key`
    header or as `Authorization: Bearer rm_...`. Keys have the format
    `rm_(live|test)_<random>`. A key resolves to exactly one project; all reads
    and writes are automatically isolated to that project and its tenant. A key
    cannot read or modify another project's data.


    ## Scopes

    Every key carries a set of scopes. Each operation requires a specific scope,
    documented in that operation's description (for example `Requires scope:
    subscribers:write`). A request whose key lacks the required scope returns
    `403`.


    The full scope taxonomy: `subscribers:read|write`, `topics:read|write`,
    `segments:read|write`, `campaigns:read|write`, `automations:read|write`,
    `custom_fields:read|write`, `sending_domains:read|write`, `consents:manage`,
    `suppressions:manage`, `reports:read`, `billing:read`, `credits:read`.


    ## Rate limiting

    Requests are limited to 60 per minute per key. The response carries
    `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`. When
    exceeded, the API returns `429` with a `Retry-After` header.


    ## Errors

    All errors use RFC 7807 `application/problem+json` with `type`, `title`,
    `status`, `detail`, `instance`, `timestamp` and (for validation) `errors`.


    ## Canonical flow: add your users to your topics

    1. `GET /topics` to discover topic keys.

    2. `POST /subscribers` with `topicKeys` + `consent` to create a subscriber
    and subscribe in one call, OR `POST /subscribers/{email}/consents` to
    subscribe an existing subscriber.

    If a topic uses double opt-in, the consent is created `PENDING_CONFIRMATION`
    and the subscriber must confirm via the email they receive before they are
    subscribed.
  contact:
    name: Railmail
    url: https://railmail.app
servers:
  - url: https://api.railmail.app
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: Subscribers
    description: Manage subscribers within the API key's project
  - name: Topics
    description: Manage subscription topics in the project
  - name: Consents
    description: Grant, read and revoke per-topic consent for a subscriber
  - name: Suppressions
    description: Manage the project suppression list
  - name: Campaigns
    description: Create, manage, schedule and send email campaigns
  - name: Segments
    description: Create, manage and populate subscriber segments
  - name: Custom Fields
    description: Define and manage subscriber custom field definitions
  - name: Automations
    description: Create, manage and control email automation workflows
  - name: Sending Domain
    description: Manage the project's custom sending domain and DNS verification
  - name: Campaign Reports
    description: Read campaign statistics, AI report, timeline and CSV export
  - name: Billing
    description: Read subscription, plans, invoices and usage for the account
  - name: AI Credits
    description: Read AI credit balance and transaction history for the account
  - name: Project
    description: Read the project the API key is scoped to
paths:
  /api/v1/custom-fields:
    post:
      tags:
        - Custom Fields
      summary: Create a custom field
      description: >-
        Creates a custom field definition. SELECT and MULTI_SELECT require
        `options`. Requires scope: `custom_fields:write`. Tenancy: scoped to the
        API key's project.
      operationId: createCustomField
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCustomFieldRequest'
            examples:
              text:
                value:
                  key: company
                  displayName: Company
                  type: TEXT
                  isRequired: false
              select:
                value:
                  key: plan
                  displayName: Plan
                  type: SELECT
                  options:
                    - value: free
                      label: Free
                    - value: pro
                      label: Pro
      responses:
        '201':
          description: Custom field created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomFieldResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    CreateCustomFieldRequest:
      type: object
      properties:
        key:
          type: string
        displayName:
          type: string
          maxLength: 100
        description:
          type: string
          maxLength: 500
          nullable: true
        type:
          type: string
          enum:
            - TEXT
            - LONG_TEXT
            - NUMBER
            - DECIMAL
            - BOOLEAN
            - DATE
            - DATETIME
            - EMAIL
            - URL
            - PHONE
            - SELECT
            - MULTI_SELECT
        isRequired:
          type: boolean
          nullable: true
        defaultValue:
          type: string
          nullable: true
        options:
          type: array
          items:
            $ref: '#/components/schemas/SelectOptionPayload'
          nullable: true
          description: Required for SELECT and MULTI_SELECT.
      required:
        - key
        - displayName
        - type
    CustomFieldResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
        key:
          type: string
        displayName:
          type: string
        description:
          type: string
          nullable: true
        type:
          type: string
        status:
          type: string
        isSystem:
          type: boolean
        isRequired:
          type: boolean
        defaultValue:
          type: string
          nullable: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        archivedAt:
          type: string
          format: date-time
          nullable: true
    SelectOptionPayload:
      type: object
      properties:
        value:
          type: string
        label:
          type: string
      required:
        - value
        - label
    ProblemDetail:
      type: object
      description: RFC 7807 problem details.
      properties:
        type:
          type: string
          format: uri
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        instance:
          type: string
          format: uri
        timestamp:
          type: string
          format: date-time
        errors:
          type: object
          additionalProperties:
            type: string
          description: Field-level validation errors, present on 400/422.
      required:
        - type
        - title
        - status
  responses:
    BadRequest:
      description: Malformed request or invalid field values.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'
    Forbidden:
      description: The API key lacks the required scope.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'
    UnprocessableEntity:
      description: The request body failed domain validation.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'
    TooManyRequests:
      description: Rate limit exceeded.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
        X-RateLimit-Limit:
          description: Requests allowed per minute.
          schema:
            type: integer
        X-RateLimit-Remaining:
          description: Requests remaining in the window.
          schema:
            type: integer
        X-RateLimit-Reset:
          description: Epoch seconds when the window resets.
          schema:
            type: integer
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'
    InternalError:
      description: Unexpected server error.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetail'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        Project-scoped API key, format rm_(live|test)_... . May also be sent as
        `Authorization: Bearer rm_...`.

````