Box Developer Documentation
 

    Custom email and notifications

    Custom email and notifications

    Email subject and body

    By default, the email sent to the signers contains a link to the document, a generic subject, and a generic message.

    If you are using templates managed within Box, the subject and message body can be set in the template itself.

    However, if you are not using templates, you can still customize the email messages sent to the signers by passing the email_subject and the email_message parameters.

    Both parameters accept strings, but the email_message parameter also accepts HTML with some limitations.

    Only some HTML tags are allowed. Links included in the message are also converted to hyperlinks in the email.

    The message parameter may contain the following HTML tags:

    • a, abbr, acronym, b, blockquote, code, em, i, ul, li, ol, strong

    Custom styles on these tags are not allowed.

    Be aware that when the text to HTML ratio is too high, the email may end up in spam filters or clipped.

    For example:

    cURL
    curl --location 'https://api.box.com/2.0/sign_requests' \
        --header 'Content-Type: application/json' \
        --header 'Authorization: Bearer ej...3t' \
        --data-raw '{
          "email_subject": "All we need is your signature to get started",
          "parent_folder": {
            "id": "234102987614",
            "type": "folder"
          },
          "source_files": [
            {
              "id": "1358047520478",
              "type": "file"
            }
          ],
          "signers": [
            {
              "email": "signer@example.com",
              "role": "signer"
            }
          ]
        }'
    

    Manual notification

    By now, you've noticed that the signature request sends an email notification to the signers by default. This email is sent from a box.com domain and email system.

    You can take over the notification process by setting the embed_url_external_user_id parameter to an identifier of your choice for a specific signer.

    By setting this parameter, the signer will not receive an email notification, and within the signature request, you get back both an embed_url and an iframeable_embed_url.

    The embed_url can be opened directly, so it is suitable for your app to send it in an email, or by any other notifications system for the signer to open.

    The iframeable_embed_url is suited to be used with the Box Embedded Sign Client, which allows you to embed the Box Sign client on an iframe within your web app.

    For example see this request:

    cURL
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer fN...dD' \
    --data-raw '{
      "is_document_preparation_needed": false,
      "parent_folder": {
        "id": "234102987614",
        "type": "folder"
      },
      "source_files": [
        {
          "id": "1355143830404",
          "type": "file"
        }
      ],
      "signers": [
        {
          "email": "signer@example.com",
          "embed_url_external_user_id": "1234",
          "role": "signer"
        }
      ]
    }'
    

    Returns (simplified):

    cURL
    {
      "is_document_preparation_needed": false,
      "signers": [
        {
          "email": "sender@example.com",
          "role": "final_copy_reader",
        },
        {
          "email": "signer@example.com",
          "role": "signer",
          "embed_url_external_user_id": "1234",
          "embed_url": "https://app.box.com/sign/document/22a990ce-4e24-463b-b2f4-124820fe161a/9331fe9ac85650d61645d4b0fd30fe3e0ebee7921720ab6ecca587654d3cd875/",
          "iframeable_embed_url": "https://app.box.com/embed/sign/document/22a990ce-4e24-463b-b2f4-124820fe161a/9331fe9ac85650d61645d4b0fd30fe3e0ebee7921720ab6ecca587654d3cd875/"
        }
      ],
      "id": "22a990ce-4e24-463b-b2f4-124820fe161a",
    }
    

    You can now take the embedded URLs and use your own notification process or embed the signature client within your own app.