SFTP integration guide
SFTP: start here
Use SFTP for recurring file-based mailing. Request access through support@uploadletters.com; use the exact connection and folder details provisioned for your account. Store credentials privately and verify the host key through your agreed channel.
Outbound contains submitted ZIP packages. Inbound contains daily mailing outputs. Provisioned folder paths select Letters, Checks or Letters with Checks; use those paths exactly.
What happens after upload
Processing validates the file and recipients. With company-enabled manual review, an email directs you to a Draft in Incomplete Orders, where you can review and pay. Otherwise processing proceeds to charging and fulfillment. There is no separate SFTP fulfill command.
Valid recipients can proceed while invalid recipients are excluded and not charged. Rejections are communicated by email, not a Failed Recipients report. Failed payment prevents placement; resolve funds and check the original order before any resubmission. SFTP does not detect duplicate ZIPs.
There is no sandbox. Do not upload a sample ZIP to a production folder as a harmless connectivity test. Samples contain illustrative records and are not bundled with deliverable PDFs.
Read sftp submit guide, sftp fields guide, sftp options guide, sftp records guide and sftp checks guide for the full workflow.
SFTP: prepare and submit a mailing package
Package contents
Include one data index per ZIP, with a lowercase .txt or .xml extension, and the PDFs that its letter rows reference. Use the package layout provisioned for your workflow. Example package contents: import.txt, recipient-one.pdf and recipient-two.pdf; alternatively import.xml can assign ranges from letters.pdf.
PDF filenames must match exactly, including case. Each TXT row must have exactly as many pipe-separated fields as the header. Preserve empty cells. Use simple values without embedded pipes in the provided templates. XML element names must match exactly; TXT headers ignore case and treat spaces and underscores equivalently.
Review the index
Use Return Envelope and Affidavit of Mailing. Old Return Envelope Type and Affidavit Option headers are not recognized and are silently ignored. Unknown headers are ignored in both formats, so a typo can silently omit an option. Missing required TXT columns reject the file; XML row-level validation rejects affected rows.
Print Type and Color Options headers must be present even when their values are blank. Blank values mean single-sided and black and white. Domestic blank Envelope Type selects by page count. International and FedEx require explicit formats.
Upload once and reconcile
Use the provisioned outbound folder for Letters, Checks or Letters with Checks. Retain your original index, ZIP filename, submitted references and receipt. Review processing/failure emails and the actual accepted mailing records. A receipt is not proof that every recipient was accepted, paid or mailed.
Do not re-upload an uncertain job until you check the original order. SFTP does not automatically identify duplicates. After a failed payment, a resubmission may be necessary but must be reconciled first.
Limits
The SFTP file size limit is 50 MB per PDF. One oversized PDF rejects the whole SFTP file. There is no fixed recipient, ZIP-size or total-page cap; per-piece envelope limits remain. Coordinate very large jobs with the team, particularly jobs that might take more than an hour to process.
SFTP: field reference
TXT headers ignore case and treat spaces/underscores equivalently. XML names are exact and do not accept underscore-style names. Unknown fields are silently ignored.
| TXT header |
Requirement |
Meaning |
| Unique ID |
Required |
Customer reference; retain locally because current Meta output lacks passthrough customer Unique ID / Letter ID columns. |
| Letter ID |
Optional |
Additional customer-provided letter reference. |
| Full Name |
Optional |
Full recipient name; the source permits this instead of separate first and last names. |
| First Name |
Required if Full_Name absent |
Recipient name component. The guide requires both when Full_Name is absent; do not substitute the API name rules. |
| Last Name |
Required if Full_Name absent |
Recipient name component. The guide requires both when Full_Name is absent; do not substitute the API name rules. |
| Company Name |
Optional |
Recipient company name. |
| Address Line 1 |
Required |
Recipient street address. |
| Address Line 2 |
Optional |
Apartment, suite or secondary address. |
| City |
Required |
Recipient city. |
| State |
Required |
Recipient state/province; domestic templates use two-letter state codes. International requires Country. |
| Zip |
Required |
Recipient ZIP; preserve as text, including leading zeros. |
| Return Company Name |
Optional |
Return company. |
| Return Full Name |
Optional |
Full return contact name. |
| Return First Name |
Optional |
Return contact first name. |
| Return Last Name |
Optional |
Return contact last name. |
| Return Address Line 1 |
Optional |
Return street address. |
| Return Address Line 2 |
Optional |
Return secondary address. |
| Return City |
Optional |
Return city. |
| Return State |
Optional |
Return state; templates use two-letter state codes. |
| Return Zip |
Optional |
Return ZIP; preserve as text. |
| Service Type |
Required |
fc, cm, cm-rre, pm, pm-box, intl-fc, rim or FedEx. Separate domestic/international and USPS/FedEx files. |
| Envelope Type |
Optional / conditional |
Domestic fc/cm/cm-rre: 10, 6x9, 9x12 or blank for automatic selection. International: explicit 10 or 9x12. FedEx: overnight or 2day required. Priority: blank/ignored. |
| Print Type |
Header required; value may be blank |
Header required; blank value is single-sided. Existing examples use simplex/duplex. |
| Color Options |
Header required; value may be blank |
Header required; blank value is black and white. Existing examples use bw/color. |
| PDF Name |
Required for letter workflow |
Filename of the source PDF inside the uploaded ZIP. Match the supplied file exactly. |
| PDF Page Numbers |
Optional |
Source XML example uses inclusive ranges such as 1-3 and 4-6. Use inclusive document page ranges and keep them within the referenced PDF. |
| Shadow |
Optional |
Additional billable First-Class copy for supported Certified Mail workflow. Verification charges also apply to shadow copies. |
| Affidavit of Mailing |
Optional |
Use Affidavit of Mailing; sb/sl/nb/nl, same for every row. Blank/omitted means none. Enabled by default. |
| Return Envelope |
Optional |
Use Return Envelope; blank means none. Enabled by default. Do not use Return Envelope Type. |
| Code Check |
Required in check folders |
Bank account UID alias; verified 26-character company bank UID. Required for Checks and Letters with Checks. |
| Amount check |
Required in check folders |
Required for check folders; check amount. |
| Memo check |
Optional |
Check memo. |
| Note 1 check |
Optional |
First check note. |
| Note 2 check |
Optional |
Second check note. |
| Date check |
Required in check folders |
Required for check folders; MM-DD-YYYY, not in the past. |
| same day mailing |
Optional |
Same Day Mailing accepts true/yes consistently across rows. Account enabled; default cutoff 11 AM Central evaluated at charging/approval. Dropped after cutoff without surcharge. |
| Country |
Conditional |
Required for international recipients. |
| Certificate of Mailing |
Conditional |
true/yes consistently; account enabled, fc only; cannot combine with Restricted Delivery. |
| Restricted Delivery |
Conditional |
true/yes consistently; account enabled, cm/cm-rre only; cannot combine with Certificate of Mailing. |
Correct optional TXT headers are Return Envelope and Affidavit of Mailing. Obsolete Return Envelope Type and Affidavit Option are ignored.
Exact XML elements
UniqueID, LetterID, FullName, FirstName, LastName, CompanyName, AddressLine1, AddressLine2, City, State, Country, Zip, ReturnCompanyName, ReturnFullName, ReturnFirstName, ReturnLastName, ReturnAddressLine1, ReturnAddressLine2, ReturnCity, ReturnState, ReturnZip, ServiceType, EnvelopeType, PrintType, ColorOptions, PDFName, PDFPageNumbers, Shadow, AffidavitOfMailing, ReturnEnvelope, CodeCheck, AmountCheck, MemoCheck, Note1Check, Note2Check, DateCheck, SameDayMailing, CertificateOfMailing, RestrictedDelivery. FedEx phone XML elements are RecipientPhoneNumber and ReturnPhone.
FedEx phone fields
| TXT header |
XML element |
Meaning |
| Return Phone |
ReturnPhone |
Sender phone. Return Phone Number is not recognized. |
| Recipient Phone Number |
RecipientPhoneNumber |
Recipient phone, with configured account default allowed. |
Use Return Phone for the sender and Recipient Phone Number for the recipient. Return Phone Number is not recognized and is silently ignored; a FedEx file missing the required sender phone is rejected. Dashes, spaces, parentheses and dots are stripped. A leading 1 or +1 is accepted; the normalized number must contain exactly 10 U.S. digits. Plain 10-digit input is recommended.
SFTP: mailing options
| service_type / Service Type |
Service |
Envelope value |
| fc |
USPS First-Class Mail |
10, 6x9, 9x12; omitted selects by page count |
| cm |
Certified Mail |
10, 6x9, 9x12; omitted selects by page count |
| cm-rre |
Certified Mail with Return Receipt Electronic |
10, 6x9, 9x12; omitted selects by page count |
| pm |
Priority Mail Flat Rate envelope |
Leave blank; ignored |
| pm-box |
Priority Mail Medium Flat Rate Box |
Leave blank; ignored |
| intl-fc |
International First-Class |
Explicit 10 or 9x12 required |
| rim |
International Registered Mail |
Explicit 10 or 9x12 required |
| FedEx |
FedEx Overnight or FedEx 2Day |
Explicit overnight or 2day required |
Use Service Type and Envelope Type headers. Do not use box as the envelope selector for a Priority Mail box; choose service pm-box and leave Envelope Type blank.
| Envelope |
Maximum physical sheets, including cover sheet |
Uploaded PDF pages, single-sided, without inserts |
Uploaded PDF pages, double-sided, without inserts |
| #10 |
5 |
4 |
8 |
| 6×9 |
16 |
15 |
30 |
| 9×12 |
70 |
69 |
138 |
These are physical-sheet limits, not interchangeable PDF-page limits. A return envelope reduces the document allowance by one single-sided page or two double-sided pages; a check consumes additional capacity. Domestic First-Class and Certified Mail can select the envelope automatically when omitted. International uses #10 or 9×12 only and requires an explicit selection.
International files require Country for recipients, explicit 10 or 9x12, and a company configuration without address verification. Do not combine international mail with checks, return envelopes or same-day mailing. Separate FedEx from USPS and international from domestic mail in different files.
Affidavits and return envelopes
Affidavit of Mailing accepts sb (signed batch), sl (signed letter), nb (notarized batch) or nl (notarized letter), consistently across the file. Blank/omitted means none. Return Envelope selects available return materials; blank means none. Existing documented codes include 9npna, 9pna and 9pa. Both features are now enabled by default on company accounts. Do not use obsolete Affidavit Option or Return Envelope Type headers.
Same-day and special options
Same Day Mailing, Certificate of Mailing and Restricted Delivery accept true/yes; use consistent values on every row. Same-day requires eligible account access and defaults to an 11 AM Central cutoff, evaluated after processing/at charging or manual approval. After cutoff or on non-mailing days, it moves to the next business mailing day without the same-day charge. Applied same-day costs $1 per piece, including extra First-Class copies. It is unavailable internationally.
Certificate of Mailing requires fc; Restricted Delivery requires cm or cm-rre. Both require account access and cannot be combined. A file violating these combination rules is rejected.
Verification
Only the company setting chooses SFTP verification; no TXT/XML verification field exists. Read sftp address verification guide for NONE/LOOKUP/BEST/BOTH, costs, selected destinations and the supplemental LOOKUP output. XML LOOKUP output currently has a known empty-file issue.
FedEx phones
FedEx Overnight and 2Day are supported. Sender and recipient phone information is required, with an account default available for recipient phone. Use Return Phone for the sender and Recipient Phone Number for the recipient. Return Phone Number is not recognized and is silently ignored; a FedEx file missing the required sender phone is rejected. Dashes, spaces, parentheses and dots are stripped. A leading 1 or +1 is accepted; the normalized number must contain exactly 10 U.S. digits. Plain 10-digit input is recommended.
SFTP: checks and letters with checks
The provisioned folder selects the workflow: Letters requires PDFs; Checks requires check fields without a PDF; Letters with Checks requires both. Checks must be enabled for the account and use a verified company bank account.
| TXT header |
XML element |
Meaning |
| Bank Account UID |
CodeCheck |
Required 26-character UID of a verified bank account. Code Check is a TXT alias. |
| Amount_check |
AmountCheck |
Required check amount. |
| Date_check |
DateCheck |
Required date in MM-DD-YYYY, not in the past. |
| Memo check |
MemoCheck |
Optional memo. |
| Note 1 check |
Note1Check |
Optional first note. |
| Note 2 check |
Note2Check |
Optional second note. |
A blank/invalid required check value rejects that row, leaving other valid rows to proceed. In Letters folders, check columns are ignored even if populated. Unknown headers are silently ignored.
Return Envelope and Affidavit of Mailing remain the correct optional headers. Check printing uses black and white and single-sided output. Confirm the bank, payee, amount, date and document assignments in your own preparation process before upload. No public bank-account creation endpoint is supplied here.
The included checks templates use deliberately non-working bank placeholders. They are format examples, not authorized payment instructions. Do not upload them unchanged.
Address verification within SFTP mailings
Company configuration
Only the company setting controls verification. There is no verification field in the TXT or XML index. Configure the required mode with our team before submitting mailings. International mailing cannot use address verification and requires a company configuration without CASS/NCOA.
| Mode |
Mailing destination and results |
| NONE |
Original address; no verification. |
| LOOKUP |
Mail to the CASS-standardized address and report forwarding information. |
| BEST |
Use forwarding information when available, otherwise the best available address. |
| BOTH |
Mail to the standardized address and an additional forwarding address when available. |
Failed verification falls back to the original address.
Results
LOOKUP accounts receive a supplemental NCOA_Addresses file in the daily Inbound folder. This comes from the mailing workflow. Known current issue: this supplemental file is empty for XML-based accounts. Metadata contains the address to which each piece was sent.
Billing
The account's configured rate applies, defaulting to $0.05 per recipient. There is no per-file verification fee for SFTP mailing orders. Unsuccessful lookups and shadow First-Class copies incur the configured verification charge. A forwarding-address copy generated by BOTH has a normal mailing charge but no additional verification fee for that generated copy. A configured zero verification price currently falls back to $0.05; it does not disable the fee.
SFTP billing and manual review
Base mailing rates include applicable postage or FedEx freight. Additional pages, color and selected add-ons are extra.
Auto Recharge
Only one reload is attempted per order. The configured reload amount must cover the entire wallet shortage. For a $500 order with $200 in the wallet, the shortage is $300. A $100 reload is insufficient: the order is refused and the card is not charged. Add funds or adjust the reload amount before retrying.
Failed payment
A failed payment prevents placement. The order remains in draft/pre-processing and failure notifications are available. Resubmission may be needed after resolving the payment issue. Check the original order first: SFTP does not automatically detect duplicate ZIP uploads.
If payment succeeds but production stalls, our team can identify the issue and restart fulfillment without charging again. Contact support with the existing order reference.
Manual review
When manual review is enabled for the company, processed SFTP orders automatically move to Incomplete Orders and a review email is sent. Review the letters and order total in the application, then pay by wallet or credit card.
SFTP: retrieve and reconcile records
Daily Inbound/MM_DD_YYYY folders contain the Meta file, Letter Images, Tracking Data, available RRE Images, Return Mail Images and Affidavit Images. LOOKUP accounts also receive NCOA_Addresses. Known issue: that file is empty for XML accounts.
Meta has one row per letter with letter ID, tracking code, serial, status, price and addresses. It currently does not include passthrough Unique ID / Letter ID columns for submitted customer references; retain your submitted index and a local reconciliation record. Extra forwarding copies can have IDs suffixed _2 and generate an additional mailing charge.
Rejected recipients are reported by email. There is no separate Failed Recipients output report. Reconcile intended, accepted, rejected and additional generated pieces rather than assuming every input row became one mailed item.
Seven days versus seven years
SFTP output folders are retained for seven days by default, subject to the configured account period. Retrieve those files within that period. Applicable mailing records remain accessible to SFTP customers through the application under the seven-year platform retention policy. Folder expiry does not mean the platform records have been deleted.
Tracking and supporting documents
Production status is separate from carrier events. First-Class Intelligent Mail barcode processing visibility is not carrier-confirmed delivery. Certified Mail, Priority Mail and FedEx provide their applicable carrier tracking. Return Receipt Electronic and affidavits are supporting records when available; they may arrive after the initial mailing outputs. Do not treat every missing artifact as an error or assume every service produces every artifact.