You open the letter attached to your year-end appeal mailing to tweak a sentence or add a merge field, and Altru throws an error instead of saving. The appeal goes out next week. Before you rebuild the letter from scratch, it’s worth working out what the error is actually objecting to, because the fix depends on what kind of problem it is.
Error messages when editing appeal mailing letters tend to fall into a handful of buckets. Below is how to tell them apart and what to do about each one. We can’t see your exact error text, so treat this as a diagnostic checklist, not a guarantee that any single step will clear it.
Start by writing down the exact error
It sounds obvious, but copy the full message, including any reference number or “details” text, before you click away. Note what you were doing at that moment: opening the letter, saving it, changing the merge template, or changing the fields the letter pulls from. Altru errors often look generic at the top and only get specific in the details. That text is also the first thing Blackbaud support will ask for.
Is the letter already in use?
A common source of trouble is editing a letter that’s tied to a mailing that has already been processed or is partway through processing. Altru is protective of records that have been used to produce output, because changing them after the fact would make your history inaccurate.
- Check the status of the appeal mailing the letter belongs to. If it has already been run, the safest move is usually to copy the letter (or create a new one) and attach the copy to a new or unprocessed mailing.
- If the same letter is shared across several mailings, an edit can be blocked or have side effects you didn’t intend. Separate letters per mailing are easier to manage.
If you aren’t sure whether Altru locks a letter once its mailing is processed in your version, test it on a throwaway mailing in your sandbox before changing anything in production.
Is the problem the merge fields?
Appeal letters pull constituent data (names, addresses, salutations, giving details) into a Word document. Errors frequently show up when the fields the letter expects don’t match the fields the mailing can supply.
- A field was removed or renamed. If someone edited the underlying field list or query after the Word template was built, the template may reference a field that no longer exists. Compare the merge fields in the document against the current field list and remove or replace anything orphaned.
- Smart fields or custom attributes changed. If the letter uses a smart field or attribute that was deleted, renamed, or restricted, the merge can fail. Check with whoever manages your smart fields.
- Salutations and addressee formats. Missing or unusual name formats on a subset of records can cause errors that only appear for certain constituents. Run the mailing’s selection as a query and look for blank addressee or salutation values.
Is the problem the Word document itself?
The template file can be the culprit even when the data is fine.
- Re-save the template as a clean .docx. Documents that have been copied from older letters many times can carry broken field codes or formatting. Paste the text into a fresh document, rebuild the merge fields, and upload that.
- Check merge field syntax. Toggle field codes in Word to make sure each field is intact and not split across formatting runs. A half-deleted merge field is easy to miss visually.
- Watch file size and embedded content. Large images, signatures pasted as high-resolution graphics, or embedded objects can make uploads fail. Compress images or use a smaller logo file.
- Close the file locally. If the document is open in Word or synced through a cloud folder while you upload or download it, you can get save or access errors.
Is it a permissions issue?
If one person gets the error and another doesn’t, look at security roles before anything else. Editing letters, mailings, and the fields behind them may require rights that a development or membership user doesn’t have by default. Have an Altru administrator try the same edit. If it works for them, the fix is a role adjustment, not a broken letter.
Is it the browser or session?
Less glamorous, but it happens. Before escalating:
- Log out completely, clear the browser cache, and try again.
- Try a different supported browser.
- Check whether pop-up blockers or download settings are interfering when Altru tries to open or return the Word file.
When to call Blackbaud support
If the error persists after you’ve ruled out a processed mailing, merge field mismatches, a damaged template, permissions, and the browser, open a case with Blackbaud. Include:
- The full error text and any reference number
- The appeal mailing name and the letter name
- What you changed right before the error first appeared
- Whether a clean copy of the letter on a new mailing shows the same error
That last point matters. If a fresh letter on a fresh mailing works, the problem is almost certainly specific to the original record or template, and support can focus there.
Habits that prevent the next one
- Keep a master copy of each letter template outside Altru, versioned by date, so you’re never editing your only copy.
- Create a new letter for each campaign instead of reusing last year’s letter on a processed mailing.
- Don’t change the field list behind a letter without checking which templates use it.
- Run a small test batch (a handful of staff or board records) before processing the full mailing, so merge problems surface while there’s still time to fix them.
Quick answers
Can I edit a letter after the appeal mailing has been processed?
Treat it as off-limits. Even where an edit is allowed, changing a letter after output has been produced makes your records harder to trust. Copy it and use the copy going forward.
The letter worked last year. Why does it fail now?
Something underneath it usually changed: a field, a smart field, a security role, or the Word file after re-saving. Compare the template’s merge fields against what the mailing currently provides.
