MailForce API

Overview

The API exposes one resource today: donations. A donation record includes the amount, the payment method, the campaign that prompted it, the donor's name and address, and the contact details we have on file. Each call returns JSON. Filtering by date is the primary access pattern.

If you previously consumed our nightly CSV export, the /donations/caging endpoint returns the same fields with the same column names, so migrating is mostly a matter of switching from a file pull to an HTTP call.

Which donations are returned

The API exposes finalized donation records only. A donation becomes visible once it has been processed by our back-office team and reached one of three terminal states:

Records still in-flight inside MailForce (statuses Open or Reconciled) and records that have been deleted are not returned. This means the same record may appear in a later sync than your first one — for example, a donation reconciled on Monday may only reach Submitted on Tuesday. Use the updated_since filter to pick up records that have changed since your previous run.

To include or isolate correspondence-only entries, use the type filter on the list endpoint: type=donor returns only records with a payment method, type=non_donor returns only correspondence-only records, and omitting the filter returns both.

Quickstart

1. Email your MailForce administrator and request API credentials. They will issue you a client ID, a client secret, and one or both of the available scopes.
2. Exchange those credentials for a short-lived access token by POSTing to /oauth/token (see Authentication).
3. Call any endpoint with the token in an Authorization: Bearer <token> header. Try https://ign.mailforceapp.com/api/v1/donations/fields first to confirm everything is wired up — it returns the list of fields your token can see.
4. Pull data. The most common pattern is a single-day fetch:

   curl -H "Authorization: Bearer $TOKEN" \
     'https://ign.mailforceapp.com/api/v1/donations?date=2026-04-25'

5. Tokens expire. When a request returns 401, repeat step 2 to obtain a fresh one. (Tokens currently last 30 days, but rely on the 401 response rather than a hard-coded TTL.)

Authentication

The API uses the OAuth 2.0 Client Credentials flow. There is no user login — your client ID and secret authenticate the calling application directly.

Exchange credentials for a token

POST https://ign.mailforceapp.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&scope=read-donations read-pii

The response contains an access_token. Send it on every API request:

Authorization: Bearer YOUR_ACCESS_TOKEN

Scopes

Scopes determine which fields you receive. We issue two:

If your token only carries read-donations, fields that require read-pii (names, addresses, phone numbers, email) are silently omitted from responses. Asking for one of those fields explicitly via the optional_fields parameter returns a 403 with the offending field names listed.

Rate limits

Each access token gets its own rate-limit bucket. Exceeding a limit returns 429 Too Many Requests with a Retry-After header indicating how long to wait.

Pagination

List endpoints return at most 50 records per page by default (maximum 200, configurable via per_page). When more results exist, a cursor is included in the response so you can fetch the next page. There are no offset / page-number parameters — cursor pagination is stable even if records are added or removed while you page through results.

Response shape

Every list response includes a meta block:

{
  "data": [ /* ... up to per_page records ... */ ],
  "meta": {
    "fields_returned": ["id", "finder", "donation_amount", "..."],
    "per_page": 50,
    "next_cursor": "eyJjcmVhdGVkX2F0Ijoi…",
    "prev_cursor": null
  }
}

• meta.next_cursor — opaque token for the next page. null when you are on the last page (no more results).
• meta.prev_cursor — token to step back to the previous page. null on the first page.
• meta.per_page — echoes the page size in effect for this response.
• meta.fields_returned — the fields included in data, after applying your scopes and any optional_fields.

Fetching the next page

Take the next_cursor value from the previous response and pass it as the cursor query parameter. Do not modify or decode the cursor — treat it as an opaque string. Keep your other filters (date_from, date_to, optional_fields, etc.) on every request; they are not encoded into the cursor.

curl -H "Authorization: Bearer $TOKEN" \
  'https://ign.mailforceapp.com/api/v1/donations?date_from=2026-04-01&date_to=2026-04-25&cursor=eyJjcmVhdGVkX2F0Ijoi…'

Worked example: pulling every donation in a window

params = { date_from: "2026-04-01", date_to: "2026-04-25", per_page: 200 }
all = []
loop:
    response = GET /api/v1/donations?{params}
    all.append(response.data)
    if response.meta.next_cursor is null:
        break
    params.cursor = response.meta.next_cursor
return all

Tips

• Increase per_page up to 200 for bulk pulls — fewer requests, fewer round trips, friendlier on rate limits.
• Going backwards: pass meta.prev_cursor as cursor to step back. Only useful when displaying paged UI; bulk syncs always go forward until next_cursor is null.
• Stable ordering: results are ordered by your chosen date_field (default created_at) in your chosen order (default asc), with id as a tiebreaker. The cursor encodes this position, so concurrent inserts will appear in subsequent pages without skipping or duplicating already-paged records. Keep date_field and order consistent across paginated requests in the same loop — changing them mid-loop will produce a fresh ordering and your cursor will no longer be valid.
• For incremental sync, pair pagination with the updated_since filter: pass an ISO-8601 timestamp from your last successful sync, then page through any records that have changed since.
• Rate-limit awareness: each page is one request against the standard limit (60/min). The /donations/caging endpoint also counts against the bulk-export limit (10/min, 200/day) — plan large pulls accordingly.

Donations

Read donations and the donor information attached to them.

curl -H "Authorization: Bearer $TOKEN" \
  'https://ign.mailforceapp.com/api/v1/donations?date=2026-04-25'

curl -H "Authorization: Bearer $TOKEN" \
  'https://ign.mailforceapp.com/api/v1/donations/caging?date=2026-04-25'

curl -H "Authorization: Bearer $TOKEN" \
  'https://ign.mailforceapp.com/api/v1/donations/9c2d…'

curl -H "Authorization: Bearer $TOKEN" \
  'https://ign.mailforceapp.com/api/v1/donations/fields'

Field reference

Every field a donation response can include is listed below. The list is generated live — what you see here matches what the API actually returns today.

• Scope — which scope your token must hold to receive this field.
• Tier — default fields are returned automatically; optional fields require ?optional_fields=name1,name2 (or ?optional_fields=* to include everything your scopes allow).
• Caging column — the column header used when calling with format=caging, matching our internal reconciliation export.

Glossary

Terms used throughout the API and the field descriptions:

Donor

The individual or organization that gives a donation. Each donor has a person record (name, contact details) and an address.

Finder

A short, unique code printed on a mailing piece (e.g. an envelope or reply card) that lets us match an incoming donation back to the specific donor and campaign that prompted it.

Mail code

A campaign code that identifies which mailing the donation responded to. Used for attribution and reporting.

White mail

A donation that arrived without a finder code attached — for example, a cheque sent in a plain envelope. These are tagged with the mail code "WM" by default.

Effective mail date

The date the donation should be reported against. Usually the date the mailing was sent; in some cases it is adjusted by an internal back-office process so that donations from related mailings group together.

Caging

The back-office process of opening, recording, and depositing donations. The /donations/caging endpoint returns the same data points used in our nightly reconciliation export.

Old_* fields

When donor or address details are corrected on the day a donation is recorded, the previous values are captured in the activity log. The Old_* fields expose those prior values, scoped to changes made on the same calendar day as the donation. They will be empty when no correction was made.

Token scope

A permission attached to your access token. We issue two scopes: read-donations (financial fields) and read-pii (donor personal information). A token can hold one or both.

Errors

The API uses standard HTTP status codes. The response body is always JSON; on errors it includes a message and (where applicable) a list of the specific fields that failed.