Cameo co-operates with a number of external services for things like sending and receiving email, taking payments and offering publically-accessible forms. This article explains what is needed to set these up.

Domains for Cameo

Cameo requires three domains to operate, which will typically be subdomains of the main domain of your website. So if that is mysite.org, you might set up something like:

  • cameo.mysite.org, where the Cameo installation is located,
  • forms.mysite.org, where forms from Cameo are fetched from to be embedded in your main site, and
  • checkin.mysite.org, for the event ticket check-in app.

Typically these will all be set up as so-called CNAMEs, in your domain provider’s control panel, referencing mysite.cameo-membership.uk. , replacing mysite with whatever your real organisation name is, of course (note the final dot is included).

If you prefer, you could use a different style for the last two, for example:

  • forms.cameo.mysite.org and checkin.cameo.mysite.org
  • cameo-forms.mysite.org and cameo-checkin.mysite.org

Hosting forms

When you create a form in Cameo, it will provide instructions for embedding this in your main website. To make this possible your website needs to be using TLS (the encryption technology that is the basis for HTTPS, pages shown with a padlock in the browser address bar). This is a de-facto requirement these days, as sites not using HTTPS shout warnings at their visitors in modern browsers. If your web hosting provider isn’t able to offer you TLS certificates free from LetsEncrypt, you really should move to one who can.

Cameo, its forms server and check.in app are all HTTPS from the outset. They cannot communicate with non-HTTPS sites. HTTPS is required to protect personal information and payment details entered into Cameo’s forms.

At the time of writing, most browsers are now insisting your web server uses TLS version 1.2 or later, or they won’t connect to them. Older web servers may only have TLS 1.0 or TLS 1.1 available. Hopefully, your provider will deal with all this for you.

Sending email

One of Cameo’s main functions is sending email to people in the database. To do this it has to connect to a service that can transmit email, known as a mail transfer agent (MTA). While most cloud servers are set up for outgoing email, or have a remote MTA they can connect to using the so-called SMTP protocol, this isn’t a great way to do it as there are often restrictions on sending bulk messages, and you have to handle bounces and spam reports manually. Domestic SMTP providers (like GMail and Fastmail) are wholly unsuitable and using them for bulk email infringes their terms and conditions.

Cameo supports most bulk email providers through SMTP. However, Cameo also directly supports Mailgun, a service designed for sending email in bulk, and this is the preferred way of doing it. Mailgun is free for up to 12,000 emails per month, which is usually plenty for a small organisation, though you will need to supply a credit card to be able to send more than 100. This is not charged unless you exceed the limit, but means they can verify your identity (as a deterrent to spammers). Most other bulk email providers, e.g. Mandrill (part of MailChimp), SendGrid and SendPulse, do not have a free tier like this.

Mailgun requires you to support modern security standards for your email:

  • SPF (which is a method for the recipient to know that the email has come from a server nominated by the sender’s domain, and not a forgery from elsewhere), and
  • DKIM (which digitally signs the email so the recipient can tell it hasn’t been tampered with en route).

You can send email as someone@mysite.org (following the example above), or use a separate domain for this, as in for example someone@mail.mysite.org. Mailgun recommends the latter, but I think the former is neater. Whether you can do that depends on whether you can identify all the places where mail is already being sent from mysite.org addresses, so you can include this in the SPF information as a legitimate sender. With a subdomain set up for the purpose, you’ll also have to set up incoming mail (which Mailgun can also provide if necessary, with instructions).

Either way, you need to tell Mailgun the domain you’ll use. It will then provide entries which you need to add to your domain provider’s DNS control panel as TXT records. If you are already sending email from the domain elsewhere, you will also need to adapt the SPF entry to include the other servers. Once these are in place Mailgun will verify them and you are ready to go.

You then require a Private API Key from Settings > API Keys on the Mailgun control panel. Give this to the Cameo adminstrator to include in the setings for your site.

Email opt-out

If you are planning to send out mailshots, one of the first things you’ll need to do is set up a page on your main website to allow opt-outs. It is a legal requirement under GDPR that all mailshots have an opt-out link or similar in the email.

To do this:

  • decide where the page will be on your website
  • add the URL of that page to Organisation Details section in Cameo, with _H_ where a unique identifier will be automatically substituted when mail is sent. For example:
    https://www.mysite.org/optout/?msg=_H_
  • Create the opt-out form in the Manage Forms section of the Forms menu.
  • Use the instructions underneath your new form to embed it in the page you chose.
  • Use the substitution {show: optout link} in your email footer. This will be replaced by the mail merge in each message with a link to the URL you provided with a unique identifier in place of the _H_.

Because the form only works with a personalised link, and that comes from an email, you need to have at least prepared one email to someone on a public list before you can configure the form. You don’t actually have to send the email, but you will need to have a public list to opt-out from and a template with that list as its audience before the form will work.

Incoming email

It is possible to set up Cameo to receive incoming email for various purposes (for example to attach to a membership record, or put a file in the file store). See help for Incoming Email on the Organisation Settings menu for how to do this.

Political boundaries

Cameo’s facilities for political representation and lobbying rely on MapIt to determine which government areas (council wards and divisions and parliamentary constituencies) members addresses are within. If you propose to use this aspect of Cameo, you’ll need a MapIt account. These are free for (fairly broadly-defined) charitable organisations; otherwise there is a somewhat costly monthly fee.

Once you have an account, you’ll need to obtain an API Key from the MapIt control panel and pass this to the Cameo administrator.

Locating memberships on a map does not depend on MapIt (that uses a combination of Ordnance Survey’s CodePoint data and OpenStreetMap’s Noiminatim search engine).

Including political representatives for those areas – to support lobbing, for example – requires connectors for those areas to be available. There is no reliable source of elected representatives in a common machine-readable format, so this relies on interpreting the information in a myriad of formats on councils’ websites. Fortunately many use a product called ModernGov to manage these, so formats tend to be quite similar, but not identical, from council to council.

Taking payments

Cameo supports the following payment methods in forms that take payment (join, membership renewal, general payment, event booking):

  • manual methods: cash, cheque, standing order and bank transfer. These simply tell the payee how to make their payment.
  • card payments: Stripe (fees: 1.4%+20p per transaction) and PayPal (fees: 3.4%+30p per transaction)
  • ApplePay and GooglePay, via Stripe, but requiring an extra set-up step in the Stripe dashboard
  • direct debits: GoCardless (fees: 1% of transactions)
  • voucher payments (similar to phone top-ups)

Stripe, PayPal and GoCardless are easy to sign up for and do not charge fees for simply having an account. PayPal, however, will require increasing onerous documentation from you are your income goes above certain thresholds, sometimes omits the card-only payment option in their forms, and is much more expensive.

Each third-party payment provider you want to support needs to be added to Cameo by an entry in the Organisation Settings > Payment Methods page. In particular, you will need to add credentials identifying your account to each of these before you can use them to take payments. The help for Payment Methods lists what these are and where to get them.

Bank Accounts

Usually you will also want to set up a bank account in Cameo for each provider in Organisation Settings > Bank Accounts. Stripe, PayPal and GoCardless can have automatic feeds to keep records in Cameo up-to-date for reconciliation against memberships.

This also requires credentials, which may or may not be the same as those for taking payments, depending on the provider (for example, you can make read-only credentials for GoCardless for the bank account that wouldn’t be suitable for taking payments). The help for Bank Accounts explains how to obtain these.

Importing existing members

You will almost certainly have existing membership records that you need to import. This is done in the Import Memberships section in the New menu.

Cameo can accept a number of formats for this based on CSV or JSON files. Note that CSV files must use UTF-8 encoding. That is not the default for Microsoft Excel or LibreOffice when you save a CSV, but it is for Google Sheets.

The structure of JSON files and the columns and their headings required for CSV files are listed in Cameo help. If you only have one individual per membership, there is an abbreviated format you can use.

Other initial setup

Basically, go through Organisation Settings entering information for each of the categories. These include

  • basic information about your organisation, so that substitutions for these work in templates
  • membership and contact types; for members you’ll include the fees for each type
  • delivery round areas if you have a distribution network for printed material. If not a single ‘MAIL’ entry will be sufficient
  • custom fields for any additional information you keep for each membership that isn’t available out of the box