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

# Custom email signatures

> Add a plain-text or HTML signature to every outgoing message from a mailbox

Save one signature per mailbox and let Inkbox add it to outgoing email.
Custom signatures are available on paid plans. Each mailbox has its own content
and on/off setting, so agents can sign with different names and contact details.

A signature is part of the email body, not an attachment. You do not need a
signature file to use one.

## API access

Use an admin API key to manage signatures for mailboxes in your organization.
Use a claimed agent’s identity-scoped API key to manage that agent’s own mailbox.
An agent-scoped key cannot change another agent’s signature.

Both use `PATCH /api/v1/mail/mailboxes/{email_address}` and the same SDK or CLI
commands below. The organization must have access to custom signatures to save
content or enable insertion. Disabling or clearing remains available without it.

## Set up in the Console

Open your mailbox's **Mailbox settings** in the
[Inkbox Console](https://inkbox.ai/console), then choose **Signature**. You can
open these settings from the Email mailbox list or the identity's inbox.

Click your saved signature or **Add signature** to open the editor.
Choose **Text** or **HTML**, then edit the content or import a file.
Choose **Save** to apply your changes. Clicking outside the editor shows a
preview without saving; click the signature again to keep editing your draft.

Turn automatic insertion on or off, then choose **Save**. Turning it off keeps
the saved content. The organization's **Email footer** setting is separate from
this mailbox setting.

## Choose a format

| Format                      | What to provide                                                                                                                                            |
| :-------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Plain text                  | A name, role, contact details, and full URLs as ordinary text.                                                                                             |
| HTML                        | An HTML fragment with basic formatting, links, optional tables, and a logo. Provide a text equivalent for plain-text messages, or let Inkbox generate one. |
| `.txt` or plain-text `.sig` | Read the file as text and use its contents as `signature_text`. The extension does not change the email format.                                            |
| `.html` or `.htm`           | Read the file as text and use its contents as `signature_html`. Use the signature fragment rather than a complete webpage.                                 |

`.sig` is not one universal file format. If a mail app exported a proprietary
signature package, first export or copy its plain text or HTML. Inkbox does not
parse signature packages or attach signature files to messages.

Each text or HTML value can contain up to **16,384 characters**. For a logo, use
an absolute HTTPS image URL such as `https://example.com/logo.png` and include
helpful alt text. Images are linked, not uploaded or attached; recipients' mail
apps may require permission to display them. Local paths, relative URLs, and
embedded image references are not supported.

Inkbox normalizes HTML to supported email formatting before saving. Read the
returned HTML to see the saved result. The generated text fallback contains
readable text, not necessarily the destination URLs of links; supply your own
text value if those URLs should appear in plain-text email.

## Configure through the SDK or CLI

Use version `0.7.1` or later of the Python SDK, TypeScript SDK, or CLI.
These examples save both formats and enable automatic insertion.

<CodeGroup>
  ```python Python theme={null}
  from inkbox import Inkbox

  inkbox = Inkbox(api_key="YOUR_API_KEY")
  mailbox = inkbox.mailboxes.update(
      "agent@inkboxmail.com",
      signature_html="<p><strong>Example Support</strong><br>example.com</p>",
      signature_text="Example Support\nexample.com",
      signature_enabled=True,
  )
  print(mailbox.signature_html)
  ```

  ```typescript TypeScript theme={null}
  import { Inkbox } from "@inkbox/sdk";

  const inkbox = new Inkbox({ apiKey: "YOUR_API_KEY" });
  const mailbox = await inkbox.mailboxes.update("agent@inkboxmail.com", {
    signatureHtml: "<p><strong>Example Support</strong><br>example.com</p>",
    signatureText: "Example Support\nexample.com",
    signatureEnabled: true,
  });
  console.log(mailbox.signatureHtml);
  ```

  ```bash CLI theme={null}
  inkbox mailbox update agent@inkboxmail.com \
    --signature-html '<p><strong>Example Support</strong><br>example.com</p>' \
    --signature-text 'Example Support — example.com' \
    --signature-enabled
  ```
</CodeGroup>

Use an admin API key or a claimed agent's key for its own mailbox. See
[Update mailbox](/docs/api/mail/mailboxes#update-mailbox) for the REST equivalent and
complete request and response fields.

### Read a signature from a file

The CLI reads the file and submits its contents. It does not attach the file.

```bash CLI theme={null}
inkbox mailbox update agent@inkboxmail.com \
  --signature-html-file signature.html \
  --signature-text-file signature.sig \
  --signature-enabled
```

Use only one content option per format: inline value, file, or clear. You can
combine an HTML option with a text option.

### Turn insertion off or clear content

Disable automatic insertion without losing either format:

```bash CLI theme={null}
inkbox mailbox update agent@inkboxmail.com --no-signature-enabled
```

Clear both saved formats and disable insertion:

```bash CLI theme={null}
inkbox mailbox update agent@inkboxmail.com \
  --clear-signature-html --clear-signature-text --no-signature-enabled
```

For SDK requests, use `None` in Python or `null` in TypeScript to clear a format.
Use `False` or `false` for the enabled setting. Omit a field to preserve it.

## Understand updates and fallbacks

* New mailboxes start with both formats `null` and `signature_enabled: false`.
* Updating HTML without a text field regenerates the text fallback. Clearing
  HTML without a text field also clears the saved text.
* Supply both fields when you want your own text fallback. A `null` text field
  still falls back to readable text from saved HTML at send time.
* To switch from HTML to text only, explicitly clear HTML and provide text in
  the same update.
* Empty or whitespace-only strings clear a format. An enabled signature with
  no content adds nothing.
* A logo-only HTML signature still appears in the HTML version. If it has no
  readable text, the plain-text version contains only your message content.

The API rejects `signature_enabled: null`; omit the field to keep the current
setting. Saving nonempty content or enabling insertion without feature access
returns `402`. Disabling or clearing remains available. An admin can check
[signature availability](/docs/api/billing#check-custom-signature-availability) before
showing configuration controls.

## What recipients receive

Inkbox applies the current enabled signature to new messages, replies,
reply-all, forwards, [draft sends](/docs/capabilities/email/drafts), and
[SMTP submissions](/docs/capabilities/email/mail-clients), when your organization has
access to custom signatures.

An HTML signature adds an HTML version to a text-only message. Recipients receive
the formatted signature, including its images and links, with a plain-text
fallback. Inkbox escapes your plain-text message when creating the HTML version.
This does not enable open tracking.

If you supply an HTML body, Inkbox preserves its formatting and inserts the
signature into it. Messages with both versions receive a signature in each.
A text-only signature does not turn a text-only message into HTML; it is formatted
as text when inserted into an existing HTML body.

The signature appears after your new content and before recognized quoted
history. If Inkbox does not recognize a mail app's quote format, it appends the
signature to the body. Attachments and original messages forwarded as attachments
are unchanged.

Saved drafts do not have a signature inserted automatically. They use the
mailbox's current signature when sent. Already composed delivery retries keep
the original signature, so later edits do not change sent history or add another
signature to that retry.

Do not manually add the same signature to each message. If your mail app adds
one locally, turn off that local signature or turn off Inkbox's automatic
insertion to avoid duplicates.

Signed or encrypted SMTP message bodies require automatic custom signature
insertion and the Inkbox branding footer to be disabled before sending.

## Signatures and the Inkbox footer

These are independent controls:

| Control                  | Scope        | Effect                                                          |
| :----------------------- | :----------- | :-------------------------------------------------------------- |
| `signature_enabled`      | One mailbox  | Adds your saved custom signature when the feature is available. |
| `remove_branding_footer` | Organization | Removes **Sent via Inkbox** on paid plans when set to `true`.   |

When both appear, your custom signature comes before the Inkbox footer.
Enabling a signature never removes the footer. Disabling a signature never
restores or removes it. See [Billing settings](/docs/api/billing#update-billing-settings)
to change the footer.

If your organization loses access to custom signatures, Inkbox retains the
saved content and enabled preference but stops inserting it. Insertion resumes
when access is restored, unless you disabled the mailbox setting.