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

# Send a fax

> Send a fax to one or more destinations. For corporate members without a fax number assigned set the 'from' parameter to 'no_number'. (Permitted scopes: **fax:all:edit**, **fax:fax:edit**). To randomly select one of the available numbers per recipient, use comma-separated string.

<Note>
  You can reuse files from existing faxes using the `from_fax` parameter instead of uploading files again. This is perfect for:

  * **Resending** a fax that failed or needs to go to the same destination
  * **Forwarding** a received fax to new recipients
  * **Combining** by sending both uploaded files and an existing fax file together (uploaded files are sent first, followed by the file from `from_fax`)

  Set `options.enhancement: false` when resending to preserve the original quality.
</Note>

<RequestExample>
  ```js NodeJS SDK theme={null}
  const axios = require('axios');
  const OutboxApiFp = require('@alohi/faxplus-api').OutboxApiFp;
  const Configuration = require('@alohi/faxplus-api').Configuration;

  const config = new Configuration({
      accessToken: accessToken,
      basePath: 'https://restapi.fax.plus/v3',
      // Header required only when using the OAuth2 token scheme
      baseOptions: {
          headers: {
            "x-fax-clientid": clientId,
          }
      }
  });

  async function sendFax() {
      const reqParams = {
          "userId": '13d8z73c',
          "payloadOutbox": {
              "comment": {
                  "tags": [
                      "tag1",
                      "tag2"
                  ],
                  "text": "text comment"
              },
              "files": [
                  "filetosend.pdf"
              ],
              "from": "+12345667",
              "options": {
                  "enhancement": true,
                  "retry": {
                      "count": 2,
                      "delay": 15
                  }
              },
              "send_time": "2000-01-01 01:02:03 +0000",
              "to": [
                  "+12345688",
                  "+12345699"
              ],
              "return_ids": true
          }
      }
      const req = await OutboxApiFp(config).sendFax(reqParams);
      const resp = await req(axios);
  }

  sendFax()
  ```

  ```python Python SDK theme={null}
  from faxplus import ApiClient, OutboxApi, OutboxComment, RetryOptions, OutboxOptions, OutboxCoverPage, PayloadOutbox, PayloadOutboxFromFax
  from faxplus.configuration import Configuration

  outbox_comment = OutboxComment(tags=['tag1', 'tag2'], text='text comment')
  retry_options = RetryOptions(count=2, delay=15)
  outbox_options = OutboxOptions(enhancement=True, retry=retry_options)
  outbox_cover_page = OutboxCoverPage(include_company_logo=True)

  # Option 1: Send with uploaded files
  payload_outbox = PayloadOutbox(
      from_number='+12345667',
      to=['+12345688', '+12345699'],
      files=['filetosend.pdf'],
      comment=outbox_comment,
      options=outbox_options,
      send_time='2000-01-01 01:02:03 +0000',
      return_ids=True,
      cover_page=outbox_cover_page
  )

  # Option 2: Resend an existing fax (no file upload needed)
  payload_resend = PayloadOutbox(
      from_number='+12345667',
      to=['+12025559876'],
      from_fax=PayloadOutboxFromFax(fax_id='abc123def456')
  )

  # Option 3: Combine uploaded files + existing fax (files go first)
  payload_combined = PayloadOutbox(
      from_number='+12345667',
      to=['+12345688'],
      files=['cover-letter.pdf'],
      from_fax=PayloadOutboxFromFax(fax_id='abc123def456'),
      options=OutboxOptions(enhancement=False)  # Preserve quality
  )

  conf = Configuration()
  conf.access_token = access_token
  # header_name and header_value required only when using the OAuth2 token scheme
  api_client = ApiClient(header_name='x-fax-clientid', header_value=client_id, configuration=conf)
  api = OutboxApi(api_client)
  resp = api.send_fax(user_id='13d8z73c', body=payload_outbox)
  ```

  ```java Java theme={null}
  /**
   * Example below uses Apache HTTP Client 4 with Fluent API
   **/

  Map<String, String> pathParams = new HashMap<>();
  pathParams.put("user_id", "'13d8z73c'");

  StrSubstitutor sub = new StrSubstitutor(values, "{", "}");
  String url = sub.replace("https://restapi.fax.plus/v3/accounts/{user_id}/outbox");

  String jsonBody = ...; // See request body example

  String result = Request
      .Post(url)
       // The x-fax-clientid header is required only when using the OAuth2 token scheme
      .addHeader("x-fax-clientid", "YOUR CLIENT_ID")
      .addHeader("Content-Type", "'application/json'")
      .addHeader("Accept", "'application/json'")
      .addHeader("Authorization", "'Bearer {access-token}'")
      .bodyString(jsonBody, "application/json")
      .execute()
      .returnContent().asString();

  System.out.println(result.toString());
  ```

  ```go Go theme={null}
  package main

  import (
         "bytes"
         "net/http"
  )

  func main() {

      headers := map[string][]string{
          // The x-fax-clientid header is required only when using the OAuth2 token scheme
          "Content-Type": []string{"application/json"},
          "Accept": []string{"application/json"},
          "Authorization": []string{"Bearer {access-token}"},
          "x-fax-clientid": []string{"YOUR CLIENT_ID"}
      }

      data := bytes.NewBuffer([]byte{jsonReq})
      req, err := http.NewRequest("POST", "https://restapi.fax.plus/v3/accounts/{user_id}/outbox", data)
      req.Header = headers

      client := &http.Client{}
      resp, err := client.Do(req)
      // ...
  }
  ```

  ```php PHP theme={null}
  <?php

  require 'vendor/autoload.php';

  $headers = array(
      'Accept' => 'application/json',
      'Authorization' => 'Bearer {access-token}',
      // The x-fax-clientid header is required only when using the OAuth2 token scheme
      'x-fax-clientid' => '{client ID}',
  );

  $client = new GuzzleHttp\Client();

  // Define array of request body.
  $request_body = ...;  // See request body example

  try {
      $response = $client->request('POST','https://restapi.fax.plus/v3/accounts/{user_id}/outbox', array(
          'headers' => $headers,
          'json' => $request_body,
          )
      );
      print_r($response->getBody()->getContents());
   }
   catch (GuzzleHttp\Exception\BadResponseException $e) {
      // handle exception or api errors.
      print_r($e->getMessage());
   }

   // ...
  ```

  ```bash cURL theme={null}
  # Send with uploaded files
  curl -X POST https://restapi.fax.plus/v3/accounts/{user_id}/outbox \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer {access-token}' \
    -H 'x-fax-clientid: YOUR_CLIENT_ID' \
    -d '{
      "from": "+12345667",
      "to": ["+12345688", "+12345699"],
      "files": ["filetosend.pdf"],
      "comment": {"text": "text comment", "tags": ["tag1", "tag2"]},
      "options": {"enhancement": true, "retry": {"count": 2, "delay": 15}},
      "return_ids": true
    }'

  # Resend an existing fax (no file upload)
  curl -X POST https://restapi.fax.plus/v3/accounts/self/outbox \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer {access-token}' \
    -H 'x-fax-clientid: YOUR_CLIENT_ID' \
    -d '{
      "from": "+12345667",
      "to": ["+12025559876"],
      "from_fax": {"fax_id": "abc123def456"}
    }'

  # Combine uploaded files + existing fax
  curl -X POST https://restapi.fax.plus/v3/accounts/self/outbox \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer {access-token}' \
    -H 'x-fax-clientid: YOUR_CLIENT_ID' \
    -d '{
      "from": "+12345667",
      "to": ["+12345688"],
      "files": ["cover-letter.pdf"],
      "from_fax": {"fax_id": "abc123def456"},
      "options": {"enhancement": false}
    }'
  ```
</RequestExample>


## OpenAPI

````yaml post /accounts/{user_id}/outbox
openapi: 3.0.1
info:
  title: Fax.Plus REST API
  description: >-
    This is the Fax.Plus API v3 developed for third party developers and
    organizations. In order to have a better coding experience with this API,
    let's quickly go through some points:<br /><br /> - This API assumes
    **/accounts** as an entry point with the base url of
    **https://restapi.fax.plus/v3**. <br /><br /> - This API treats all date and
    times sent to it in requests as **UTC**. Also, all dates and times returned
    in responses are in **UTC**<br /><br /> - Once you have an access_token, you
    can easily send a request to the resource server with the base url of
    **https://restapi.fax.plus/v3** to access your permitted resources. As an
    example to get the user's profile info you would send a request to
    **https://restapi.fax.plus/v3/accounts/self** when **Authorization** header
    is set to **Bearer YOUR_ACCESS_TOKEN** and custom header of
    **x-fax-clientid** is set to YOUR_CLIENT_ID
  version: 3.4.0
  contact:
    name: Fax.Plus
    email: info@fax.plus
    url: https://github.com/alohi
servers:
  - url: https://restapi.fax.plus/v3
  - url: /v3
security: []
paths:
  /accounts/{user_id}/outbox:
    post:
      tags:
        - Outbox
      summary: Send a fax
      description: >-
        Send a fax to one or more destinations. For corporate members without a
        fax number assigned set the 'from' parameter to 'no_number'. (Permitted
        scopes: **fax:all:edit**, **fax:fax:edit**). To randomly select one of
        the available numbers per recipient, use comma-separated string.
      operationId: sendFax
      parameters:
        - name: user_id
          in: path
          required: true
          schema:
            type: string
            default: self
          description: >-
            User ID. Use 'self' for your own account, or provide a specific user
            ID for corporate member accounts.
          example: self
      requestBody:
        $ref: '#/components/requestBodies/Outbox'
      responses:
        '201':
          $ref: '#/components/responses/SendFax'
        '400':
          $ref: '#/components/responses/Error'
        '500':
          $ref: '#/components/responses/ServerError'
      security:
        - oauth2:
            - all
        - personal_access_token:
            - fax:all:edit
            - fax:fax:edit
components:
  requestBodies:
    Outbox:
      x-go-name: SendFaxRequest
      description: Request to send new outbound fax
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PayloadOutbox'
  responses:
    SendFax:
      description: Outbox fax has been created successfully
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SendFaxResponse'
    Error:
      description: Error object in case there's a problem with given data
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: invalid_user_id
            description: Invalid user id given
    ServerError:
      description: Error object in case there's a server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: internal_server_error
            description: An unexpected error happened, please contact support
  schemas:
    PayloadOutbox:
      description: >-
        Model for creating new outbound fax. **Note:** At least one of `files`
        or `from_fax` must be provided.
      example:
        comment:
          tags:
            - tag1
            - tag2
          text: text comment
        files:
          - filetosend.pdf
        from: '+12345667'
        options:
          enhancement: true
          retry:
            count: 2
            delay: 15
        send_time: 2000-01-01 01:02:03 +0000
        to:
          - '+12345688'
          - '+12345699'
        return_ids: true
      properties:
        from:
          description: >-
            Number to use for sending the fax. Use comma-separated string to
            randomly select one of the numbers per-recipient
          pattern: >-
            ^(([+][0-9]{8,}([*]{0,10}[0-9]+)?)|(no_number)|(NO_NUMBER))(,(([+][0-9]{8,}([*]{0,10}[0-9]+)?)|(no_number)|(NO_NUMBER)))*$
          type: string
          example: +41782222222,+41782222333,+41782222444
        to:
          description: List of fax destination numbers
          items:
            pattern: ^[+][0-9]{8,}([*]{0,10}[0-9]+)?$
            type: string
          minItems: 1
          type: array
        files:
          description: >-
            List of file names to send. Files should be uploaded beforehand.
            **Required unless `from_fax` is provided.** Can be combined with
            `from_fax` to append additional files before the referenced fax
            file.
          items:
            type: string
          type: array
        from_fax:
          description: >-
            Reference to an existing fax whose file to reuse (resend/forward).
            **Required unless `files` is provided.** Can be combined with
            `files` to prepend additional documents before the referenced fax
            file.
          type: object
          required:
            - fax_id
          properties:
            fax_id:
              type: string
              description: >-
                Session ID of the fax to reuse (the 'id' field from fax
                list/send responses)
              example: abc123def456
            user_id:
              type: string
              description: >-
                User ID who owns the fax. Use 'self' for your own faxes, or a
                member ID for corporate subordinate faxes. Defaults to 'self'.
              default: self
              example: self
        comment:
          $ref: '#/components/schemas/OutboxComment'
        options:
          $ref: '#/components/schemas/OutboxOptions'
        send_time:
          description: 'Date when to send the fax. Format: **YYYY-MM-DD HH:mm:ss +HHMM**'
          pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2} [0-9]{2}:[0-9]{2}:[0-9]{2} [+|-][0-9]{4}
          type: string
        return_ids:
          description: Return scheduled fax IDs to use for tracking and with webhooks
          type: boolean
          default: false
        resolution:
          description: 'Fax resolution. Valid values: **fine**, **superfine**'
          type: string
          enum:
            - fine
            - superfine
          default: fine
        cover_page:
          $ref: '#/components/schemas/OutboxCoverPage'
      required:
        - to
        - from
      type: object
      additionalProperties: false
    SendFaxResponse:
      x-go-name: SendFaxResult
      description: >-
        Send fax handle response, will contain Destination-to-ID mapping if the
        corresponding flag was provided
      example:
        ids:
          '+1234567890': 1a2b3c4d5e6f7890
          '+1345678912': 78901a2b3c4d5e6f
      properties:
        ids:
          description: Destination-to-ID mapping
          type: object
          additionalProperties: true
      type: object
      additionalProperties: false
    Error:
      properties:
        description:
          type: string
        error:
          type: string
      additionalProperties: false
    OutboxComment:
      properties:
        tags:
          default: []
          items:
            type: string
          type: array
        text:
          default: ''
          type: string
      description: Comment to set for the fax job
      type: object
    OutboxOptions:
      properties:
        enhancement:
          description: Text enhancement. Set to True to optimize fax file for text.
          default: true
          type: boolean
        retry:
          $ref: '#/components/schemas/RetryOptions'
        partially_sent_retry:
          type: boolean
          description: >-
            Enable automatic retry for partially sent faxes. Please make sure
            that the remote will accept chunked submissions before using it
      description: Additional configuration for sending a fax
      type: object
    OutboxCoverPage:
      description: Fax cover page
      type: object
      required:
        - name_to
        - name_from
        - subject
      properties:
        name_to:
          type: string
          description: TO field on the cover page
        name_from:
          type: string
          description: FROM field on the cover page
        subject:
          type: string
          description: SUBJECT field on the cover page
        flags:
          type: array
          description: Cover page flags
          items:
            $ref: '#/components/schemas/CoverPageFlags'
        message:
          type: string
          description: MESSAGE field on the cover page
        include_company_logo:
          type: boolean
          description: Use company logo on the cover page
    RetryOptions:
      description: Fax retry settings
      example:
        retry:
          count: 2
          delay: 10
      properties:
        count:
          description: Number of tries to send the fax
          maximum: 3
          minimum: 0
          type: integer
        delay:
          description: Delay in seconds between two retries
          maximum: 180
          minimum: 0
          type: integer
      type: object
      additionalProperties: false
    CoverPageFlags:
      description: Allowed flags for the cover page
      type: string
      enum:
        - urgent
        - for_review
        - please_reply
        - confidential
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth2 Authorization Grant
      flows:
        authorizationCode:
          authorizationUrl: >-
            https://accounts.fax.plus/login?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=http://localhost&scope=all
          tokenUrl: https://accounts.fax.plus/token
          refreshUrl: >-
            https://accounts.fax.plus/token?grant_type=refresh_token&refresh_token=YOUR_REFRESH_TOKEN
          scopes:
            all: >-
              for now when a user grants permission, all grants will be
              permitted
    personal_access_token:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Personal Access Token (PAT) is a Bearer token used for secure API calls.
        For direct API calls, the PAT is used in the Authorization header as
        'Bearer {PAT}'. For MCP usage, configure your PAT in your MCP client
        settings (e.g., in your IDE's MCP server configuration) - authentication
        will be handled automatically.

````