SEsendfox
Contacts

List contacts

Changed on

Returns a paginated list of contacts (100 per page by default, up to 1000 via per_page).

Supports engagement filtering through filter[...] query parameters, so you can answer questions like "who last opened over a year ago" without paging the whole account. All filter conditions are AND-ed. Pass count_only=true to get just the number of matches — the cheapest way to size an audience before acting on it.

get/contacts

Request

  • Base URL
    https://api.sendfox.com
  • Auth
    OAuth 2
    Authorization codehttps://sendfox.com/oauth/authorize
    Token URLhttps://sendfox.com/oauth/token

Query parameters

querystring

Search query for filtering contacts

unsubscribedboolean

Filter unsubscribed contacts

emailstring

Filter by specific email

per_pageinteger

Contacts per page

count_onlyboolean

Return only the number of matching contacts, with no contact records

filter[status]'active' | 'engaged' | 'inactive' | 'new' | 'unconfirmed' | 'unsubscribed' | 'bounced' | 'bounce_paused' | 'invalid'

Engagement status

filter[last_opened_after]string date-time

Contacts whose most recent open is on or after this date

filter[last_opened_before]string date-time

Contacts whose most recent open is before this date. Excludes contacts who never opened — use filter[never_opened] for those.

filter[last_clicked_after]string date-time

Contacts whose most recent click is on or after this date

filter[last_clicked_before]string date-time

Contacts whose most recent click is before this date

filter[last_sent_after]string date-time

Contacts last sent to on or after this date

filter[last_sent_before]string date-time

Contacts last sent to before this date

filter[created_after]string date-time

Contacts created on or after this date

filter[created_before]string date-time

Contacts created before this date

filter[never_opened]boolean

Only contacts who have never opened an email

filter[never_clicked]boolean

Only contacts who have never clicked a link

filter[never_sent]boolean

Only contacts who have never been sent an email

filter[in_list_ids]integer[]

Only contacts still subscribed to any of these lists. Members who unsubscribed from the list are not matched, so results may be smaller than before per-list unsubscribe shipped.

filter[not_in_list_ids]integer[]

Exclude contacts who are members of any of these lists, whether or not they unsubscribed from it.

filter[tag_ids]integer[]

Only contacts still subscribed to any of these tags. Somebody who opted out of the tag keeps it but is not matched. Same rule as filter[in_list_ids]; see the tag_ids note in the bulk-action filter schema.

filter[not_tag_ids]integer[]

Exclude contacts carrying any of these tags

Response

Successful response

OR

Changes

  • ae5d5ba1d502Revision changes
    • breaking

      the // response's property type changed from object to no type for status

    • breaking

      removed the required property /// from the response with the status

    • warning

      removed the optional property /// from the response with the status

    • warning

      removed the optional property /// from the response with the status

    • warning

      removed the optional property /// from the response with the status

    • warning

      removed the optional property /// from the response with the status

    • warning

      removed the optional property /// from the response with the status

    • warning

      removed the optional property /// from the response with the status

    • warning

      removed the optional property /// from the response with the status

    • info

      added the new enum value bounce_paused to the query request parameter filter[status]

    • info

      added the non-success response with the status

    • info

      added subschema #2 to the // response property allOf list for the response status

  • c5728da3037fRevision changes
    • breaking

      added subschema #1 subschema #2 to the response body oneOf list for the response status

    • breaking

      the response's body type changed from object to no type for status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • info

      added the new optional query request parameter count_only

    • info

      added the new optional query request parameter filter[created_after]

    • info

      added the new optional query request parameter filter[created_before]

    • info

      added the new optional query request parameter filter[in_list_ids]

    • info

      added the new optional query request parameter filter[last_clicked_after]

    • info

      added the new optional query request parameter filter[last_clicked_before]

    • info

      added the new optional query request parameter filter[last_opened_after]

    • info

      added the new optional query request parameter filter[last_opened_before]

    • info

      added the new optional query request parameter filter[last_sent_after]

    • info

      added the new optional query request parameter filter[last_sent_before]

    • info

      added the new optional query request parameter filter[never_clicked]

    • info

      added the new optional query request parameter filter[never_opened]

    • info

      added the new optional query request parameter filter[never_sent]

    • info

      added the new optional query request parameter filter[not_in_list_ids]

    • info

      added the new optional query request parameter filter[not_tag_ids]

    • info

      added the new optional query request parameter filter[status]

    • info

      added the new optional query request parameter filter[tag_ids]

    • info

      added the new optional query request parameter per_page

    • info

      added the non-success response with the status