Field Limits & Character Encoding

When you send mail through the API, two different kinds of limits apply: fixed length caps on a few recipient fields, and a physical fit test on the message itself. This page covers both, plus how characters are counted, what happens when a value goes over, and how %FIRST_NAME% handles multi-word names.

Everything here applies to every mailer type (postcards, letters, notecards, MagnaCards, gift cards) unless a section says otherwise.

Recipient field limits

Field	Limit	Over the limit
name	40 characters	Silently shortened to 40 (see below)
company	40 characters	Silently shortened by dropping whole words from the end
custom1 through custom10	No fixed cap	Stored in full; the message fit test below still applies after merge
address, address2, city, province, postal_code	No fixed cap	Validated for deliverability, not length

Details on name: the value is trimmed, and anything past 40 characters is cut at character 40 with no error returned. If a too-long name contains an ampersand (for example Jonathan Smith & Elizabeth Smith-Harrington), only the part before the & is kept. A name submitted in ALL CAPS is converted to title case (MARY BETH JONES prints as Mary Beth Jones).

tip

If a greeting matters, keep name under 40 characters yourself. The API will not warn you that it shortened one.

How characters are counted

Limits count Unicode characters (code points), not UTF-8 bytes and not UTF-16 code units. José is 4 characters, and Anne-Marie Müller-Schmidt is 25.

In practice the distinction rarely matters, because of the encoding rule below: every character the printer accepts occupies exactly one byte in its character set, so within the accepted alphabet, characters and bytes are the same count.

Accepted characters: Windows-1252

Recipient name and address fields (name, company, address, address2, city, province, postal_code, country) must be encodable as Windows-1252, the character set the print pipeline uses. That covers:

• The full basic Latin alphabet, digits, and common punctuation
• Western European accented characters: é, ñ, ü, ç, à, and the rest of the Latin-1 range
• A few extras such as curly quotes and the Euro sign

It does not cover emoji, or scripts outside extended Latin (Cyrillic, Greek, CJK, Arabic, and so on). A recipient field containing one of these is rejected at submit with a 422 validation error that names the offending characters by code point, for example:

{
  "errors": {
    "recipients.0.name": [
      "The recipients.0.name contains characters that cannot be encoded for print: U+1F33B."
    ]
  }
}

Nothing is charged when a request is rejected this way. The same check runs again at print time as a safety net; a recipient that slips through (for example, added to a mailing list before this check existed) fails as an individual piece rather than printing garbled.

The message body is not validated against this list at submit, but it goes through the same print pipeline - keep it to the same character set. Accents are fine; emoji will not print.

Message size: a fit test, not a character count

There is no fixed character limit on message. The real constraint is physical: the message, rendered in your chosen handwriting style, size, and color, has to fit the printable area of the mailer. A notecard's inside panel is roughly 5.5 x 4.25 inches; wide handwriting styles and larger sizes fit fewer characters than compact ones, and so does copy heavy in wide letters like "m" and "w".

What happens when it does not fit:

• At submit: the API renders your message as a check and rejects the order with HTTP 400 and the message Message Content Too Large for Notecard - Please reduce size or change handwriting style. (or the equivalent for the mailer type). Nothing is charged or mailed. Messages of roughly 500 characters or fewer skip this submit-time check; one that still cannot fit (for example at the largest handwriting size) fails at print time as described next.
• At print, after variables merge: the submit check runs on your message as written, with %FIRST_NAME%, %CUSTOM1% and the other replacement variables still unexpanded. If a long merged value pushes one recipient's finished message past the fit, that piece fails individually - it is not printed truncated. The order item's status is failed and its failure reason reads Handwritten Message Too Large, which you can read per recipient through the order items endpoint.

So the API never silently truncates a message. A message either prints in full or that piece is rejected or failed with an explicit error.

tip

If your app caps message length, a cap of 250-500 characters is comfortably safe for a notecard at default settings. To be certain with your exact template, send your longest realistic values (longest name, longest custom field contents) with "preview": true - you get back rendered PNGs of the piece without placing an order, so you can see exactly what fits. See the preview notes in the API overview.

How %FIRST_NAME% splits names

%FIRST_NAME% and %LAST_NAME% are derived from the recipient's single name field at print time:

1. Common titles are stripped: Mr, Mrs, Ms, Miss, Dr, Master, Mr & Mrs, with or without periods. All periods are removed.
2. If the name contains and, or, or &, it is treated as a couple: everything up to and including the word after the connector becomes the first name. John and Jane Smith gives %FIRST_NAME% = John and Jane, %LAST_NAME% = Smith.
3. Otherwise the name splits on the first space: the first word is %FIRST_NAME%, everything after it is %LAST_NAME%.

Consequences for compound first names:

name as submitted	%FIRST_NAME%	%LAST_NAME%
Mary Beth Jones	Mary	Beth Jones
Anne-Marie Dubois	Anne-Marie	Dubois
John and Jane Smith	John and Jane	Smith
Dr. James Wilson	James	Wilson

A space-separated compound first name like Mary Beth is not kept together - only Mary prints. Hyphenated names survive intact because the split is on spaces.

If your data has compound first names and the greeting has to be exact, put the greeting name in a custom field and use that variable instead:

{
  "name": "Mary Beth Jones",
  "custom1": "Mary Beth",
  "address": "123 Main St"
}

with a message that opens Hi %CUSTOM1%, instead of Hi %FIRST_NAME%,. Custom fields merge exactly as submitted, with no splitting or title-casing.

Related

• Replacement Variables
• API & Developer Documentation
• API Test Mode
• Notecards