How to fix unexpected header/footer in recent maillings

Published
2022-06-30 02:39
Written by
artfulrobot - member of the CiviCRM community - view blog guidelines

If you’re starting to see unexpected content at the top and/or bottom of your mailings, this may be to do with a recent upgrade (to 5.49.0+). For example, you might see text like “default HTML header”, or a footer offering opt-out where there previously was none. You might also see old headers/footers that you used to use.

Why has this happened?

(If you don’t care and just want a fix, skip to the next heading!)

CiviCRM has long had a feature enabling you to define sets of standard headers/footers for use on mailings. You were able to set one header and one footer to be the default ones, which meant they would be applied to every mailing that did not specify a different one, so long as that header/footer was also set active.

The problem was created by a clean-up of database field definitions. The is active field for headers/footers was always supposed to be a boolean (i.e. Yes, or No) but it could also include a null value. The clean-up was going to fix this, since null here is not helpful. It fixed it by making null values Yes (because Yes is a sensible default for new components). In turn, this meant that previously inactive components (null usually behaves like a No) became active, so started appearing on mailings again.

Nowadays, most of us use the drag-n-drop Mosaico editor to craft our maliings, and this assumes control over the whole mailing, so it does not offer you a choice of header/footer. This adds to the confusion because you have no visibility and no way to fix a mailing that has already been drafted (or sent, of course).

How to fix.

You can’t:

  • change an email once it’s been sent. Like you can’t change a letter once you’ve posted it.
  • change a mailing that has been drafted or scheduled, without having some developer-style access (covered below)

But: you can:

  • fix it for future mailings.
  • fix it for draft/scheduled mailings if you have developer access
  • fix it for future mailings that are made from copies of existing mailings if you have developer access

Fix it for future mailings

Head over to Administer » CiviMail » Headers, Footers and Automated Messages

For each Header and Footer component that you don’t need/want, click Edit and change the Default to No and the Enabled also to No.

If you use Mosaico, you should not have any header/footer that is marked as a default.

That’s it done; future mailings won’t use any of these components. (Note, this is not necessary, but you might want to blank the contents of these to be extra safe. To do this, remove all the text from the Body - HTML Format field, and remove all the text from the Body - TEXT Format section and then put a single space in. Without that single space in the text box it won’t let you save.)

Note that this won’t fix it if you start a new mailing by re-using an old one. You must start afresh with a new mailing.

Fix existing draft/scheduled mailings, and future mailings made from re-using old ones - requires developer skills

If you have access to SQL, then you can fix it as follows. Please note that with SQL you can seriously destroy your data extremely efficiently. You should (a) already be confident in your skills and tools, (b) take care still, and (c) make a backup before you start.

The following assumes that you’ve not intended to use mailing headers or footers for ages, which might not be true in your case.

First, figure out which mailings have been affected by running this:

SELECT id, created_date, name, header_id, footer_id
FROM civicrm_mailing
WHERE header_id IS NOT NULL OR footer_id IS NOT NULL
ORDER BY id DESC;

This will give you a list of mailings that have used footers/headers, starting with the most recently created ones. You’ll probably note a few with recent dates and then a jump to some much older dates from way back before you started using Mosaico. For me, trouble began at the end of May, with mailing ID 1234 (ok, it had a different number to that).

You might want to take a copy of that output, so you know which mailings were affected (as you won’t be able to tell after the next step).

Next, remove the headers/footers from all mailings from 1234 onward (where 1234 is the earliest recent problem mailing - it won’t be 1234 on your CRM!), like so:

UPDATE civicrm_mailing
SET footer_id = NULL, header_id = NULL
WHERE id >= 1234;

This will fix existing mailings and any copies made through “re-use mailing” of affected mailings. For mailings in progress it will fix the ones generated from this moment on. But surely you didn’t do this while a mailing was in progress, right? No, but maybe you ‘paused’ a mailing while you did it, in which case it will affect the ones that are generated after you resume it.

Q. I don’t know/have access to SQL, but can I do this with the API?

A. Hmmm. Maybe. The following untested API4 call will probably work, however mailings are strange things, and sometimes writing a change to a mailing will result in the recipients being re-calculated, which could be problematic. If you find out, do post a comment!

\Civi\Api4\Mailing::update()
  ->addValue('header_id', NULL)
  ->addValue('footer_id', NULL)
  ->addWhere('id', '>=', 1234)
  ->execute();

Is this going to happen again?

No it’s not likely; changes like this happen extremely rarely, and even then, they are unlikely to cause a problem.

But it does highlight a good-to-be-aware-of thing which is that software is constantly evolving; it must do to survive, and that any change can bring unintended consequences.

This is why people are encouraged to test new versions of CiviCRM before it’s released, so that problems might be spotted earlier and affect fewer people. Testing has costs, of course, but then there are costs to problems caused by lack of testing, too, so it’s worth considering what your organisation needs and budgeting accordingly.

Since you’re still reading(!), it’s also why CiviCRM has thousands of automated tests that get run continuously against every change. These tests aim to cover all the key functions of the CRM, and they help ensure things don’t go backwards (called “regressions”). Of course you can’t write a test for everything, and occasionally things slip through, but all developers are encouraged to ensure their changes and new features come with automated tests as part of our quality control. All changes are reviewed by humans, too.

Also worth noting is that this blog post came about after a discussion on the community chat - if you’re not already signed up, you should be, it’s a friendly place to find out more, and play a part in making CiviCRM better for everyone.

Filed under

Comments

Thank you for the heads up. I don't understand the part about "If you use Mosaico, you should not have any header/footer that is marked as a default." Why not? We have a header and footer marked as default with Mosaico emails, and it seems to work fine.