09 · MailMarco API

Marketing

Contacts, consent, segments and broadcasts. The rule language is small on purpose — every field is an enum, every value is a bound parameter.

Contacts#

A contact is an email address plus optional profile fields and a bag of tenant-defined properties. Emails are normalised — trimmed and lower-cased — before storage and lookup, so one address is one contact no matter how it was typed.

curl -X POST https://api.mailmarco.com/v1/contacts \
  -H "authorization: Bearer $MAILMARCO_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "email": "[email protected]",
    "firstName": "Ada",
    "locale": "en-GB",
    "properties": { "plan": "pro", "seats": 12 },
    "consentStatus": "subscribed",
    "consentSource": "signup-form"
  }'

CSV and bulk import#

curl -X POST https://api.mailmarco.com/v1/contacts/import \
  -H "authorization: Bearer $MAILMARCO_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "csv": "email,first_name,plan\[email protected],Ada,pro\[email protected],Grace,free\n",
    "upsert": true
  }'

{
  "created": 2,
  "updated": 0,
  "skipped": 0,
  "errors": []
}

CSV format

A header row is required and must include an email column. Recognised headers map to contact fields; every unrecognised header becomes a custom property, which is how the plan column above lands in properties.plan.

• Header matching is case-insensitive; property keys keep the header's original case.
• Empty cells are omitted rather than written as empty strings.
• Rows are validated with the same schema as single creates. A bad row is reported in errors by zero-based index and skipped; the rest still import.
• Duplicates inside one payload are collapsed before writing, last occurrence wins.
• Imported contacts default to source: "import" when the column is absent.

GET /v1/contacts/export returns the whole list as CSV (text/csv, as an attachment) with the columns email, first_name, last_name, locale, timezone, source, consent_status, consent_at, bounced, properties. Cells beginning with =, +, - or @ are neutralised so the file cannot execute formulas when opened in a spreadsheet.

The ?envelope=true flag#

List routes return a bare JSON array by default, because shipped clients parse them that way. Pass envelope=true (or 1) to get totals instead:

curl "https://api.mailmarco.com/v1/contacts?limit=50&offset=0&envelope=true" \
  -H "authorization: Bearer $MAILMARCO_API_KEY"

# => { "data": [ … ], "total": 1842, "limit": 50, "offset": 0 }

This applies to GET /v1/contacts and GET /v1/broadcasts/:id/recipients. Other list routes have no envelope option.

Topics and double opt-in#

A topic is a named subscription — “Product updates”, “Weekly digest”. Contacts subscribe per topic, and segments can filter on topic state.

curl -X POST https://api.mailmarco.com/v1/topics \
  -H "authorization: Bearer $MAILMARCO_API_KEY" \
  -H "content-type: application/json" \
  -d '{"key":"product-updates","name":"Product updates","doubleOptIn":true}'

{
  "subscription": { "status": "pending", "…": "…" },
  "confirmToken": "…"
}

The rest of the topic surface is conventional: GET /v1/topics, GET /v1/topics/:id, PATCH /v1/topics/:id (everything except key), DELETE /v1/topics/:id, and POST /v1/topics/:id/unsubscribe with the same body as subscribe.

Segments#

curl -X POST https://api.mailmarco.com/v1/segments/preview \
  -H "authorization: Bearer $MAILMARCO_API_KEY" \
  -H "content-type: application/json" \
  -d '{"rule":{"field":"consentStatus","cmp":"eq","value":"subscribed"}}'

Also available: GET /v1/segments, GET /v1/segments/:id, PATCH /v1/segments/:id and DELETE /v1/segments/:id.

The segment rule language#

A rule is either a single condition or a group of rules combined with a boolean operator.

{ "field": "consentStatus", "cmp": "eq", "value": "subscribed" }

{
  "op": "and",
  "rules": [
    { "field": "consentStatus", "cmp": "eq",       "value": "subscribed" },
    { "field": "bounced",       "cmp": "eq",       "value": false },
    { "field": "lastActiveAt",  "cmp": "gte",      "value": { "daysAgo": 90 } },
    {
      "op": "or",
      "rules": [
        { "field": "properties.plan", "cmp": "in",  "value": ["pro", "enterprise"] },
        { "field": "topic.product-updates", "cmp": "eq", "value": "subscribed" }
      ]
    }
  ]
}

Allowed fields

field is not free text. It must be one of the contact columns below, or match properties.<key> or topic.<key>. Anything else is rejected before any query is built.

Comparators and values

A date field accepts a relative value: { "daysAgo": 90 } resolves to the instant 90 days before evaluation, with daysAgo between 0 and 36,500. String values are capped at 1024 characters.

Broadcasts#

Broadcast statuses are draft, scheduled, sending, sent, canceled and failed. Note the single L here — unlike a cancelled single message.

Every broadcast message is sent with RFC 8058 one-click unsubscribe headers pointing at a signed token URL:

List-Unsubscribe: <https://api.mailmarco.com/p/u/eyJ…>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

Unsubscribe and preference center#

The /p/* routes are public and unauthenticated. They are mounted outside /v1 precisely so that is obvious. Every one is gated on an HMAC-signed opaque token and nothing else — no id, email or organization appears in any path, query or body.

The same preference data is available to you authenticated, keyed by contact id: GET /v1/contacts/:id/preferences and PATCH /v1/contacts/:id/preferences, with the same body shape.

Suppression still applies on top of consent — see Deliverability.