Menu
GETPOST campaigns/ User APIService tier

GET ?space_id= : the space's campaigns, newest first (filters: status, enrollment_mode). POST {space_id, name, connection_instance_id, connector_slug, from_email, from_name?, reply_to?, audience_query_string?, enrollment_mode?, steps}: create a draft. Launch it with campaigns/<id>/launch/.

URL

  • User APIhttps://sales.mattering.io/api/user/v1/campaigns/
  • Service tierhttps://sales.mattering.io/api/internal/campaigns/

Body keys (JSON)

KeyRequiredDefault
audience_query_stringoptional or conditionalnone
cold_settingsoptional or conditionalnone
connection_instance_idoptional or conditionalnone
connector_slugoptional or conditionalnone
enrollment_modeoptional or conditionalnone
from_emailoptional or conditionalnone
from_nameoptional or conditionalnone
nameoptional or conditionalnone
physical_addressoptional or conditionalnone
reply_tooptional or conditionalnone
sender_mailbox_idsoptional or conditionalnone
sending_modeoptional or conditionalnone
space_idoptional or conditionalnone
stepsoptional or conditionalnone

Keys the view reads. A key not in this list is ignored by the view, silently. Where a key is required only for some actions (for example the action dispatch), the description above says which.

Pagination

Accepts limit and offset. The response meta carries total, returned, has_more and next_offset.

Responses

200 data and meta envelope

{
  "data": {
    "campaigns": [
      {
        "enrolled_count": 0,
        "last_added_at": null,
        "id": "...",
        "name": "...",
        "status": "...",
        "enrollment_mode": "...",
        "last_enrolled_at": "...",
        "audience_query_string": "...",
        "audience_description": "...",
        "connection_instance_id": "...",
        "connector_slug": "...",
        "reply_capture": "...",
        "from_email": "...",
        "from_name": "...",
        "reply_to": "...",
        "steps": [
          "..."
        ],
        "sending_mode": "...",
        "pause_reason": "...",
        "cold": {
          "sender_mailboxes": [
            {
              "id": "...",
              "mailbox_email": "...",
              "provider": "...",
              "status": "...",
              "problem": {
                "error": "...",
                "detail": "..."
              },
              "sending": "...",
              "warmup": "...",
              "sent_today_this_campaign": "..."
            }
          ],
          "settings": "...",
          "settings_overrides": {
            "...": "..."
          },
          "hard_limits": {
            "daily_cap_max": "...",
            "daily_cap_default": "...",
            "warmup_schedule": {
              "...": "..."
            },
            "min_gap_minutes_floor": "...",
            "max_gap_minutes_ceiling": "...",
            "bounce_rate_limit": "...",
            "opt_out_rate_limit": "...",
            "health_min_sends": "..."
          },
          "physical_address": "...",
          "physical_address_source": "...",
          "physical_address_override": "...",
          "ad_notice": {
            "enabled": true,
            "text": "..."
          },
          "footer_preview": "...",
          "send_window": {
            "timezone": "...",
            "open_now": "...",
            "next_opens_at": "2026-01-01T00:00:00Z"
          },
          "attestation": "...",
          "attestation_valid": "...",
          "attestation_version": "...",
          "pending_changes": [
            "..."
          ],
          "launch_blockers": [
            {
              "error": "...",
              "detail": "..."
            }
          ],
          "sending_blocked": {
            "error": "...",
            "detail": "..."
          },
          "recipient_counts": "..."
        },
        "counts": {
          "sent": 0,
          "replied": 0,
          "unsubscribed": 0,
          "failed": 0,
          "bounced": 0
        },
        "space_id": "...",
        "created_by": "...",
        "launched_at": "...",
        "created_at": "...",
        "updated_at": "..."
      }
    ]
  },
  "meta": {
    "total": 0,
    "limit": 0,
    "offset": 0,
    "returned": 0,
    "has_more": true,
    "next_offset": 0
  }
}

201 data and meta envelope

{
  "data": {
    "campaign": {
      "enrolled_count": 0,
      "last_added_at": null,
      "id": "...",
      "name": "...",
      "status": "...",
      "enrollment_mode": "...",
      "last_enrolled_at": "...",
      "audience_query_string": "...",
      "audience_description": "...",
      "connection_instance_id": "...",
      "connector_slug": "...",
      "reply_capture": "...",
      "from_email": "...",
      "from_name": "...",
      "reply_to": "...",
      "steps": [
        "..."
      ],
      "sending_mode": "...",
      "pause_reason": "...",
      "cold": {
        "sender_mailboxes": [
          {
            "id": "...",
            "mailbox_email": "...",
            "provider": "...",
            "status": "...",
            "problem": {
              "error": "...",
              "detail": "..."
            },
            "sending": "...",
            "warmup": "...",
            "sent_today_this_campaign": "..."
          }
        ],
        "settings": "...",
        "settings_overrides": {
          "...": "..."
        },
        "hard_limits": {
          "daily_cap_max": "...",
          "daily_cap_default": "...",
          "warmup_schedule": {
            "...": "..."
          },
          "min_gap_minutes_floor": "...",
          "max_gap_minutes_ceiling": "...",
          "bounce_rate_limit": "...",
          "opt_out_rate_limit": "...",
          "health_min_sends": "..."
        },
        "physical_address": "...",
        "physical_address_source": "...",
        "physical_address_override": "...",
        "ad_notice": {
          "enabled": true,
          "text": "..."
        },
        "footer_preview": "...",
        "send_window": {
          "timezone": "...",
          "open_now": "...",
          "next_opens_at": "2026-01-01T00:00:00Z"
        },
        "attestation": "...",
        "attestation_valid": "...",
        "attestation_version": "...",
        "pending_changes": [
          "..."
        ],
        "launch_blockers": [
          {
            "error": "...",
            "detail": "..."
          }
        ],
        "sending_blocked": {
          "error": "...",
          "detail": "..."
        },
        "recipient_counts": "..."
      },
      "counts": {
        "sent": 0,
        "replied": 0,
        "unsubscribed": 0,
        "failed": 0,
        "bounced": 0
      },
      "space_id": "...",
      "created_by": "...",
      "launched_at": "...",
      "created_at": "...",
      "updated_at": "..."
    }
  },
  "meta": {
    "total": 0,
    "limit": 0,
    "offset": 0,
    "returned": 0,
    "has_more": true,
    "next_offset": 0
  }
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
400cold_only_field
400connection_not_allowed
400invalid_cold_settings
400invalid_connection
400invalid_email
400invalid_enrollment_mode
400invalid_json
400invalid_sending_mode
400invalid_steps
400missing_field
400non_email_step
403unknown_user
404space_not_found_or_forbidden

Example

curl -X POST "https://sales.mattering.io/api/user/v1/campaigns/" \
  -H "Authorization: Bearer $MATTERING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "audience_query_string": "...",
  "cold_settings": "...",
  "connection_instance_id": "...",
  "connector_slug": "...",
  "enrollment_mode": "...",
  "from_email": "...",
  "from_name": "...",
  "name": "..."
}'

Source: CRMCore/campaign_api.py (campaign_api.campaigns)

GET campaigns/connections/ User APIService tier

The organization's active email-sending connections (Postmark, Mailgun, SMTP), for connection_instance_id + connector_slug on create. 503 when the connector service can't be reached.

URL

  • User APIhttps://sales.mattering.io/api/user/v1/campaigns/connections/
  • Service tierhttps://sales.mattering.io/api/internal/campaigns/connections/

Responses

200 data and meta envelope

{
  "data": {
    "connections": [
      "..."
    ]
  },
  "meta": {
    "total": 0
  }
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
503connections_unavailable

Example

curl -X GET "https://sales.mattering.io/api/user/v1/campaigns/connections/" \
  -H "Authorization: Bearer $MATTERING_API_KEY"

Source: CRMCore/campaign_api.py (campaign_api.campaign_connections)

GETPATCH campaigns/mailing-address/ User APIService tier

The workspace postal address every cold email's footer carries (a campaign's own ``physical_address`` overrides it). GET ?space_id=; PATCH {space_id, address_line1?, address_line2?, city?, state?, postal_code?, country?}. ``complete`` says whether it is enough to launch (street, city or postal code, country).

URL

  • User APIhttps://sales.mattering.io/api/user/v1/campaigns/mailing-address/
  • Service tierhttps://sales.mattering.io/api/internal/campaigns/mailing-address/

Query parameters

NameDefault
space_idnone

Body keys (JSON)

KeyRequiredDefault
address_line1optional or conditionalnone
address_line2optional or conditionalnone
cityoptional or conditionalnone
countryoptional or conditionalnone
postal_codeoptional or conditionalnone
space_idoptional or conditionalnone
stateoptional or conditionalnone

Keys the view reads. A key not in this list is ignored by the view, silently. Where a key is required only for some actions (for example the action dispatch), the description above says which.

Responses

200 data and meta envelope

{
  "data": {
    "mailing_address": {
      "formatted": "...",
      "complete": true,
      "space_id": "..."
    }
  }
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
400invalid_json
400missing_field
400no_writable_fields
404space_not_found_or_forbidden

Example

curl -X PATCH "https://sales.mattering.io/api/user/v1/campaigns/mailing-address/" \
  -H "Authorization: Bearer $MATTERING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "address_line1": "...",
  "address_line2": "...",
  "city": "...",
  "country": "...",
  "postal_code": "...",
  "space_id": "...",
  "state": "..."
}'

Source: CRMCore/campaign_api.py (campaign_api.mailing_address)

GET campaigns/sender-mailboxes/ User APIService tier

GET ?space_id= : the caller's own connected mailboxes in the space, each with ``eligible`` / ``problem`` for cold sending and its sending stats (sent today, cap, today's limit while ramping, paused + reason, staff review, recent bounce and opt-out rates).

URL

  • User APIhttps://sales.mattering.io/api/user/v1/campaigns/sender-mailboxes/
  • Service tierhttps://sales.mattering.io/api/internal/campaigns/sender-mailboxes/

Query parameters

NameDefault
space_idnone

Responses

200 data and meta envelope

{
  "data": {
    "mailboxes": [
      {
        "id": "...",
        "mailbox_email": "...",
        "provider": "...",
        "status": "...",
        "problem": {
          "error": "...",
          "detail": "..."
        },
        "sending": "...",
        "warmup": "...",
        "sent_today_this_campaign": "..."
      }
    ]
  },
  "meta": {
    "total": 0
  }
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
400missing_field
404space_not_found_or_forbidden

Example

curl -X GET "https://sales.mattering.io/api/user/v1/campaigns/sender-mailboxes/?space_id=..." \
  -H "Authorization: Bearer $MATTERING_API_KEY"

Source: CRMCore/campaign_api.py (campaign_api.sender_mailboxes)

GETPATCH campaigns/sender-mailboxes/{mailbox_id}/ User APIService tier

GET: one of the caller's mailboxes with its cold sending stats and warmup. PATCH {daily_cap?: 1-100 | null, dkim_selector?: str | null, resume?: true}: change its cap (raising it is a material change for the cold sequences using it), set a custom DKIM selector for the readiness check (blank or null: Google's default ``google``), or resume it after an automatic pause. Resuming is human only, and refused while the mailbox waits for staff review (``staff_review_required``).

URL

  • User APIhttps://sales.mattering.io/api/user/v1/campaigns/sender-mailboxes/{mailbox_id}/
  • Service tierhttps://sales.mattering.io/api/internal/campaigns/sender-mailboxes/{mailbox_id}/

Path parameters

NameType
mailbox_iduuid

Body keys (JSON)

KeyRequiredDefault
daily_capoptional or conditionalnone
dkim_selectoroptional or conditionalnone
resumeoptional or conditionalnone

Keys the view reads. A key not in this list is ignored by the view, silently. Where a key is required only for some actions (for example the action dispatch), the description above says which.

Responses

200 data and meta envelope

{
  "data": {
    "mailbox": {
      "id": "...",
      "mailbox_email": "...",
      "provider": "...",
      "status": "...",
      "problem": {
        "error": "...",
        "detail": "..."
      },
      "sending": "...",
      "warmup": "...",
      "sent_today_this_campaign": "..."
    }
  }
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
400invalid_daily_cap
400invalid_dkim_selector
400invalid_json
400no_writable_fields
403not_mailbox_owner
404mailbox_not_found

Example

curl -X PATCH "https://sales.mattering.io/api/user/v1/campaigns/sender-mailboxes/MAILBOX_ID/" \
  -H "Authorization: Bearer $MATTERING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "daily_cap": "...",
  "dkim_selector": "...",
  "resume": "..."
}'

Source: CRMCore/campaign_api.py (campaign_api.sender_mailbox_detail)

POST campaigns/sender-mailboxes/{mailbox_id}/readiness/ User APIService tier

POST: re-run the sending-domain readiness checks for one of the caller's mailboxes now (SPF, DKIM at its selector, DMARC, MX, Spamhaus DBL, domain age). At most once per 5 minutes per mailbox: a repeat is 429 ``readiness_rate_limited`` with ``retry_after`` seconds. Returns the mailbox with its warmup (``warmup.readiness`` holds the checks).

URL

  • User APIhttps://sales.mattering.io/api/user/v1/campaigns/sender-mailboxes/{mailbox_id}/readiness/
  • Service tierhttps://sales.mattering.io/api/internal/campaigns/sender-mailboxes/{mailbox_id}/readiness/

Path parameters

NameType
mailbox_iduuid

Responses

200 data and meta envelope

{
  "data": {
    "mailbox": {
      "id": "...",
      "mailbox_email": "...",
      "provider": "...",
      "status": "...",
      "problem": {
        "error": "...",
        "detail": "..."
      },
      "sending": "...",
      "warmup": "...",
      "sent_today_this_campaign": "..."
    }
  },
  "meta": {
    "ready": "...",
    "checked_at": "2026-01-01T00:00:00Z"
  }
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
403not_mailbox_owner
404mailbox_not_found
429readiness_rate_limited

Example

curl -X POST "https://sales.mattering.io/api/user/v1/campaigns/sender-mailboxes/MAILBOX_ID/readiness/" \
  -H "Authorization: Bearer $MATTERING_API_KEY"

Source: CRMCore/campaign_api.py (campaign_api.sender_mailbox_readiness)

GETPATCH campaigns/{campaign_id}/ User APIService tier

GET: one campaign. PATCH: change the keys sent. A draft can change anything; once launched only the name can change, except that a cold sequence can still change its steps, audience, mailboxes, settings and address: a material change (campaign_cold.material_changes) pauses it with ``pause_reason: reattestation_required`` until the owner attests again (meta.reattestation_required).

URL

  • User APIhttps://sales.mattering.io/api/user/v1/campaigns/{campaign_id}/
  • Service tierhttps://sales.mattering.io/api/internal/campaigns/{campaign_id}/

Path parameters

NameType
campaign_iduuid

Responses

200 data and meta envelope

{
  "data": {
    "campaign": {
      "enrolled_count": 0,
      "last_added_at": null,
      "id": "...",
      "name": "...",
      "status": "...",
      "enrollment_mode": "...",
      "last_enrolled_at": "...",
      "audience_query_string": "...",
      "audience_description": "...",
      "connection_instance_id": "...",
      "connector_slug": "...",
      "reply_capture": "...",
      "from_email": "...",
      "from_name": "...",
      "reply_to": "...",
      "steps": [
        "..."
      ],
      "sending_mode": "...",
      "pause_reason": "...",
      "cold": {
        "sender_mailboxes": [
          {
            "id": "...",
            "mailbox_email": "...",
            "provider": "...",
            "status": "...",
            "problem": {
              "error": "...",
              "detail": "..."
            },
            "sending": "...",
            "warmup": "...",
            "sent_today_this_campaign": "..."
          }
        ],
        "settings": "...",
        "settings_overrides": {
          "...": "..."
        },
        "hard_limits": {
          "daily_cap_max": "...",
          "daily_cap_default": "...",
          "warmup_schedule": {
            "...": "..."
          },
          "min_gap_minutes_floor": "...",
          "max_gap_minutes_ceiling": "...",
          "bounce_rate_limit": "...",
          "opt_out_rate_limit": "...",
          "health_min_sends": "..."
        },
        "physical_address": "...",
        "physical_address_source": "...",
        "physical_address_override": "...",
        "ad_notice": {
          "enabled": true,
          "text": "..."
        },
        "footer_preview": "...",
        "send_window": {
          "timezone": "...",
          "open_now": "...",
          "next_opens_at": "2026-01-01T00:00:00Z"
        },
        "attestation": "...",
        "attestation_valid": "...",
        "attestation_version": "...",
        "pending_changes": [
          "..."
        ],
        "launch_blockers": [
          {
            "error": "...",
            "detail": "..."
          }
        ],
        "sending_blocked": {
          "error": "...",
          "detail": "..."
        },
        "recipient_counts": "..."
      },
      "counts": {
        "sent": 0,
        "replied": 0,
        "unsubscribed": 0,
        "failed": 0,
        "bounced": 0
      },
      "space_id": "...",
      "created_by": "...",
      "launched_at": "...",
      "created_at": "...",
      "updated_at": "..."
    }
  }
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
400invalid_json
400no_writable_fields
404not_found
409campaign_not_draft

Example

curl -X GET "https://sales.mattering.io/api/user/v1/campaigns/CAMPAIGN_ID/" \
  -H "Authorization: Bearer $MATTERING_API_KEY"

Source: CRMCore/campaign_api.py (campaign_api.campaign_detail)

GETPOST campaigns/{campaign_id}/attestation/ User APIService tier

GET: the statement to confirm (version, confirmations, LIA line), the current attestation, whether it is valid, pending material changes and the attestation history. POST {version, confirmations: {key: true} | [key], legitimate_interest_assessment?: bool}: the owner attests. Human only (``human_required`` 403 for agents and services). Re-attesting a sequence paused with reattestation_required resumes it.

URL

  • User APIhttps://sales.mattering.io/api/user/v1/campaigns/{campaign_id}/attestation/
  • Service tierhttps://sales.mattering.io/api/internal/campaigns/{campaign_id}/attestation/

Path parameters

NameType
campaign_iduuid

Body keys (JSON)

KeyRequiredDefault
confirmationsoptional or conditionalnone
legitimate_interest_assessmentoptional or conditionalfalse
versionoptional or conditionalnone

Keys the view reads. A key not in this list is ignored by the view, silently. Where a key is required only for some actions (for example the action dispatch), the description above says which.

Responses

200 data and meta envelope

{
  "data": {
    "statement": "...",
    "attestation": "...",
    "attestation_valid": "...",
    "pending_changes": [
      "..."
    ],
    "history": "...",
    "campaign_status": "...",
    "pause_reason": "..."
  }
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
400invalid_json
404not_found

Example

curl -X POST "https://sales.mattering.io/api/user/v1/campaigns/CAMPAIGN_ID/attestation/" \
  -H "Authorization: Bearer $MATTERING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "confirmations": "...",
  "legitimate_interest_assessment": false,
  "version": "..."
}'

Source: CRMCore/campaign_api.py (campaign_api.campaign_attestation)

POST campaigns/{campaign_id}/launch/ User APIService tier

Launch a draft: enroll the audience and start sending.

Refused with 409 ``{"error": "cold_recipients", "detail", "count", "stages"}`` when the audience holds contacts in stages that can't receive campaigns (Sales Campaigns only go to warm contacts). Send {"exclude_cold_stages": true} to exclude those stages from the audience and launch, the API form of "Exclude them and launch".

URL

  • User APIhttps://sales.mattering.io/api/user/v1/campaigns/{campaign_id}/launch/
  • Service tierhttps://sales.mattering.io/api/internal/campaigns/{campaign_id}/launch/

Path parameters

NameType
campaign_iduuid

Body keys (JSON)

KeyRequiredDefault
exclude_cold_stagesoptional or conditionalnone

Keys the view reads. A key not in this list is ignored by the view, silently. Where a key is required only for some actions (for example the action dispatch), the description above says which.

Responses

200 data and meta envelope

{
  "data": {
    "campaign": {
      "enrolled_count": 0,
      "last_added_at": null,
      "id": "...",
      "name": "...",
      "status": "...",
      "enrollment_mode": "...",
      "last_enrolled_at": "...",
      "audience_query_string": "...",
      "audience_description": "...",
      "connection_instance_id": "...",
      "connector_slug": "...",
      "reply_capture": "...",
      "from_email": "...",
      "from_name": "...",
      "reply_to": "...",
      "steps": [
        "..."
      ],
      "sending_mode": "...",
      "pause_reason": "...",
      "cold": {
        "sender_mailboxes": [
          {
            "id": "...",
            "mailbox_email": "...",
            "provider": "...",
            "status": "...",
            "problem": {
              "error": "...",
              "detail": "..."
            },
            "sending": "...",
            "warmup": "...",
            "sent_today_this_campaign": "..."
          }
        ],
        "settings": "...",
        "settings_overrides": {
          "...": "..."
        },
        "hard_limits": {
          "daily_cap_max": "...",
          "daily_cap_default": "...",
          "warmup_schedule": {
            "...": "..."
          },
          "min_gap_minutes_floor": "...",
          "max_gap_minutes_ceiling": "...",
          "bounce_rate_limit": "...",
          "opt_out_rate_limit": "...",
          "health_min_sends": "..."
        },
        "physical_address": "...",
        "physical_address_source": "...",
        "physical_address_override": "...",
        "ad_notice": {
          "enabled": true,
          "text": "..."
        },
        "footer_preview": "...",
        "send_window": {
          "timezone": "...",
          "open_now": "...",
          "next_opens_at": "2026-01-01T00:00:00Z"
        },
        "attestation": "...",
        "attestation_valid": "...",
        "attestation_version": "...",
        "pending_changes": [
          "..."
        ],
        "launch_blockers": [
          {
            "error": "...",
            "detail": "..."
          }
        ],
        "sending_blocked": {
          "error": "...",
          "detail": "..."
        },
        "recipient_counts": "..."
      },
      "counts": {
        "sent": 0,
        "replied": 0,
        "unsubscribed": 0,
        "failed": 0,
        "bounced": 0
      },
      "space_id": "...",
      "created_by": "...",
      "launched_at": "...",
      "created_at": "...",
      "updated_at": "..."
    },
    "recipients_created": true,
    "excluded_stages": "..."
  }
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
400invalid_json
400not_launchable
404not_found
409invalid_status
500launch_failed

Example

curl -X POST "https://sales.mattering.io/api/user/v1/campaigns/CAMPAIGN_ID/launch/" \
  -H "Authorization: Bearer $MATTERING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "exclude_cold_stages": "..."
}'

Source: CRMCore/campaign_api.py (campaign_api.campaign_launch)

GET campaigns/{campaign_id}/recipients/ User APIService tier

A campaign's recipients with status, skip reason and progress, paged. Filters: ``status``, ``skip_reason`` (code, prefix match so ``casl_canada`` matches ``casl_canada:email_domain``), ``email``.

URL

  • User APIhttps://sales.mattering.io/api/user/v1/campaigns/{campaign_id}/recipients/
  • Service tierhttps://sales.mattering.io/api/internal/campaigns/{campaign_id}/recipients/

Path parameters

NameType
campaign_iduuid

Pagination

Accepts limit and offset. The response meta carries total, returned, has_more and next_offset.

Responses

200 data and meta envelope

{
  "data": {
    "recipients": [
      {
        "id": "...",
        "contact": {
          "id": "...",
          "email": "...",
          "first_name": "...",
          "last_name": "...",
          "business": "..."
        },
        "status": "...",
        "skip_reason": "...",
        "skip_detail": "...",
        "current_step": "...",
        "steps_total": 0,
        "next_send_at": "...",
        "sender_mailbox": {
          "id": "...",
          "mailbox_email": "..."
        },
        "first_sent_at": "...",
        "last_sent_at": "...",
        "retry_count": 0,
        "last_error": "...",
        "pause": {
          "...": "..."
        },
        "created_at": "..."
      }
    ]
  },
  "meta": {
    "total": 0,
    "limit": 0,
    "offset": 0,
    "returned": 0,
    "has_more": true,
    "next_offset": 0
  }
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
404not_found

Example

curl -X GET "https://sales.mattering.io/api/user/v1/campaigns/CAMPAIGN_ID/recipients/" \
  -H "Authorization: Bearer $MATTERING_API_KEY"

Source: CRMCore/campaign_api.py (campaign_api.campaign_recipients)

GETPOST campaigns/{campaign_id}/recipients/{recipient_id}/ User APIService tier

One recipient of a campaign; POST resumes, re-pauses or removes it.

GET: the recipient (status, progress, pause). POST {action: "resume" | "pause_until" | "remove", until?: "YYYY-MM-DD"}: override one contact's schedule. resume ends an out-of-office or manual pause (the next email goes out at the next sending slot); pause_until holds the next email until the sending window on that date (after today, at most 60 days out); remove takes the contact out of the sequence. Only for recipients still in the sequence (recipient_not_active 409); resume needs a paused one (not_paused 409). Each change writes a timeline entry on the contact.

URL

  • User APIhttps://sales.mattering.io/api/user/v1/campaigns/{campaign_id}/recipients/{recipient_id}/
  • Service tierhttps://sales.mattering.io/api/internal/campaigns/{campaign_id}/recipients/{recipient_id}/

Path parameters

NameType
campaign_iduuid
recipient_iduuid

Body keys (JSON)

KeyRequiredDefault
actionoptional or conditionalnone
untiloptional or conditionalnone

Keys the view reads. A key not in this list is ignored by the view, silently. Where a key is required only for some actions (for example the action dispatch), the description above says which.

Responses

200 data and meta envelope

{
  "data": {
    "recipient": {
      "id": "...",
      "contact": {
        "id": "...",
        "email": "...",
        "first_name": "...",
        "last_name": "...",
        "business": "..."
      },
      "status": "...",
      "skip_reason": "...",
      "skip_detail": "...",
      "current_step": "...",
      "steps_total": 0,
      "next_send_at": "...",
      "sender_mailbox": {
        "id": "...",
        "mailbox_email": "..."
      },
      "first_sent_at": "...",
      "last_sent_at": "...",
      "retry_count": 0,
      "last_error": "...",
      "pause": {
        "...": "..."
      },
      "created_at": "..."
    }
  }
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
400invalid_json
404not_found
404recipient_not_found

Example

curl -X POST "https://sales.mattering.io/api/user/v1/campaigns/CAMPAIGN_ID/recipients/RECIPIENT_ID/" \
  -H "Authorization: Bearer $MATTERING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "action": "...",
  "until": "..."
}'

Source: CRMCore/campaign_api.py (campaign_api.campaign_recipient)

POST email-events/inbound/ User APIService tier

POST to email-events/inbound/. derived from route

This read is not paginated. It returns at most 255 rows and does not report a total, so a result of exactly 255 may be truncated.

URL

  • User APIhttps://sales.mattering.io/api/user/v1/email-events/inbound/
  • Service tierhttps://sales.mattering.io/api/internal/email-events/inbound/

Body keys (JSON)

KeyRequiredDefault
connector_instance_idoptional or conditionalnone
from_emailoptional or conditionalnone
headersoptional or conditionalnone
html_bodyoptional or conditionalnone
in_reply_tooptional or conditionalnone
metadataoptional or conditionalnone
organization_idoptional or conditionalnone
provideroptional or conditionalnone
provider_message_idoptional or conditionalnone
received_atoptional or conditionalnone
subjectoptional or conditionalnone
text_bodyoptional or conditionalnone

Keys the view reads. A key not in this list is ignored by the view, silently. Where a key is required only for some actions (for example the action dispatch), the description above says which.

Responses

200 bare JSON object (no envelope)

{
  "status": "ok",
  "matched": true,
  "auto_reply": true
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
400invalid_payload
401unauthorized

Example

curl -X POST "https://sales.mattering.io/api/user/v1/email-events/inbound/" \
  -H "Authorization: Bearer $MATTERING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "connector_instance_id": "...",
  "from_email": "...",
  "headers": "...",
  "html_body": "...",
  "in_reply_to": "...",
  "metadata": "...",
  "organization_id": "...",
  "provider": "..."
}'

Source: CRMCore/campaign_inbound.py (campaign_inbound.inbound_email_event)

GETPOST suppressions/ User APIService tier

GET: the space's suppression list, newest first. Filters: ``email`` (exact, any case), ``reason``, ``since`` (ISO date or datetime, created on or after). POST ``{space_id, email, reason, note?}``: add an address. Idempotent on space + email: a repeat returns the existing row (200, its original reason kept) instead of a second one (201).

URL

  • User APIhttps://sales.mattering.io/api/user/v1/suppressions/
  • Service tierhttps://sales.mattering.io/api/internal/suppressions/

Body keys (JSON)

KeyRequiredDefault
emailoptional or conditionalnone
noteoptional or conditionalnone
reasonoptional or conditionalnone
space_idoptional or conditionalnone

Keys the view reads. A key not in this list is ignored by the view, silently. Where a key is required only for some actions (for example the action dispatch), the description above says which.

Pagination

Accepts limit and offset. The response meta carries total, returned, has_more and next_offset.

Responses

200 data and meta envelope

{
  "data": {
    "suppression": {
      "id": "...",
      "email": "...",
      "reason": "...",
      "note": "...",
      "source_campaign_id": "...",
      "space_id": "...",
      "created_at": "..."
    }
  },
  "meta": {
    "created": false
  }
}

200 data and meta envelope

{
  "data": {
    "suppressions": [
      {
        "id": "...",
        "email": "...",
        "reason": "...",
        "note": "...",
        "source_campaign_id": "...",
        "space_id": "...",
        "created_at": "..."
      }
    ]
  },
  "meta": {
    "total": 0,
    "limit": 0,
    "offset": 0,
    "returned": 0,
    "has_more": true,
    "next_offset": 0
  }
}

201 data and meta envelope

{
  "data": {
    "suppression": {
      "id": "...",
      "email": "...",
      "reason": "...",
      "note": "...",
      "source_campaign_id": "...",
      "space_id": "...",
      "created_at": "..."
    }
  },
  "meta": {
    "created": true
  }
}

Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).

Errors

StatusCode
400invalid_email
400invalid_json
400invalid_since
400missing_field
404space_not_found_or_forbidden

Example

curl -X POST "https://sales.mattering.io/api/user/v1/suppressions/" \
  -H "Authorization: Bearer $MATTERING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "...",
  "note": "...",
  "reason": "...",
  "space_id": "..."
}'

Source: CRMCore/campaign_api.py (campaign_api.suppressions)

All Sales resources
Start Free Explore our Products