Communications

Read communication coverage target history

Finds a permitted target across all target types/statuses while respecting program/source/channel context. Returns its projection, current queue summary and one newest-first timeline page; there is no timeline total/page metadata. A full timeline event can be context-only, so check qualifies_for_target. Requires communications_coverage enabled (or the configured explicit environment opt-in), an active non-disabled user and communications_coverage_view. Program and donor-form access restrict every surface; mailbox quick links additionally require email_manager/manage_email. Requires permission: one of communications_coverage_view.

GET

admin

communications

coverage

targets

{coverageTargetId}

Read communication coverage target history

curl --request GET \
  --url https://api.gratona.com/v1/admin/communications/coverage/targets/{coverageTargetId} \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.gratona.com/v1/admin/communications/coverage/targets/{coverageTargetId}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.gratona.com/v1/admin/communications/coverage/targets/{coverageTargetId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.gratona.com/v1/admin/communications/coverage/targets/{coverageTargetId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.gratona.com/v1/admin/communications/coverage/targets/{coverageTargetId}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.gratona.com/v1/admin/communications/coverage/targets/{coverageTargetId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "data": {
    "target": {
      "id": 42,
      "client_id": 42,
      "coverage_target_id": 42,
      "donor_entity_id": 42,
      "donor_id": 42,
      "entity_id": 42,
      "program_id": 42,
      "assigned_admin_id": 42,
      "latest_thread_id": 42,
      "target_key": "donor:42",
      "target_type": "sponsorship_pair",
      "basis_type": "commitment",
      "target_status": "active",
      "coverage_status": "never_covered",
      "target_started_at": "2026-10-20 12:00:00",
      "target_ended_at": "2026-10-20 12:00:00",
      "created_at": "2026-10-20 12:00:00",
      "updated_at": "2026-10-20 12:00:00",
      "last_qualifying_touch_at": "2026-10-20 12:00:00",
      "last_any_written_touch_at": "2026-10-20 12:00:00",
      "last_context_only_touch_at": "2026-10-20 12:00:00",
      "latest_inbound_at": "2026-10-20 12:00:00",
      "qualifying_count": 1,
      "context_count": 1,
      "event_count": 1,
      "pending_approval_count": 1,
      "unread_inbound_count": 1,
      "covered_30d": 1,
      "severity": 1,
      "quick_links": {
        "open_donor_url": "/app/view_donor/42",
        "open_recipient_url": "/app/view_donor/42",
        "open_message_manager_url": "/app/view_donor/42",
        "open_coverage_url": "/app/view_donor/42",
        "compose_url": "/app/view_donor/42"
      },
      "has_thread": true,
      "has_conversation_thread": true,
      "latest_inbound_unread": true,
      "latest_thread_status": "<string>",
      "assigned_admin_name": "Example",
      "donor_name": "Example",
      "entity_name": "Example",
      "program_name": "Example",
      "programs_summary": "Example",
      "timeline": [
        "<unknown>"
      ]
    },
    "timeline": [
      {
        "event_at": "2026-10-20T12:00:00Z",
        "source_type": "message_manager",
        "channel": "email",
        "coverage_scope": "recipient_specific",
        "direction": "outbound",
        "delivery_status": "sent",
        "qualifies_for_target": true,
        "label": "Education update"
      }
    ],
    "queue_state": {
      "latest_thread_id": 42,
      "latest_thread_status": "<string>",
      "assigned_admin_id": 42,
      "assigned_admin_name": "Example",
      "unread_inbound_count": 1,
      "pending_approval_count": 1
    },
    "actions": {
      "open_donor_url": "/app/view_donor/42",
      "open_recipient_url": "/app/view_donor/42",
      "open_message_manager_url": "/app/view_donor/42",
      "open_coverage_url": "/app/view_donor/42",
      "compose_url": "/app/view_donor/42"
    }
  }
}

{
  "message": "Unauthorized",
  "status": "error"
}

{
  "message": "Not Found",
  "status": "error"
}

{
  "errors": {},
  "status": "error",
  "message": "The given data was invalid."
}

Authorizations

Authorization

string

header

required

Passport bearer token authentication for legacy admin sessions.

Path Parameters

coverageTargetId

integer

required

Coveragetarget id in the current organization.

Query Parameters

target_type

enum<string>

Target type. Validation: sometimes, string; allowed values: sponsorship_pair, donor, donor_program, all.

Available options:

sponsorship_pair,

donor,

donor_program,

all

rollup_type

enum<string>

Rollup type. Validation: sometimes, string; allowed values: recipient, program.

Available options:

recipient,

program

source_types

enum<string>[]

Source types. Validation: sometimes, array. Arrays also accept comma-separated strings.

Source types item. Validation: string; allowed values: message_manager, recipient_portal, mailing, newsletter, system_email.

Available options:

message_manager,

recipient_portal,

mailing,

newsletter,

system_email

program_ids

integer[]

Program ids. Validation: sometimes, array. Arrays also accept comma-separated strings.

Program ids item. Validation: integer, min:1.

Required range: x >= 1

target_statuses

enum<string>[]

Target statuses. Validation: sometimes, array. Arrays also accept comma-separated strings.

Target statuses item. Validation: string; allowed values: active, due, inactive, archived.

Available options:

active,

due,

inactive,

archived

coverage_statuses

enum<string>[]

Coverage statuses. Validation: sometimes, array. Arrays also accept comma-separated strings.

Coverage statuses item. Validation: string; allowed values: welcome_gap, never_covered, only_context, stale_30, stale_60, stale_90, covered.

Available options:

welcome_gap,

never_covered,

only_context,

stale_30,

stale_60,

stale_90,

covered

stale_days

enum<integer>

Stale days. Validation: sometimes, integer; allowed values: 30, 60, 90.

Available options:

30,

60,

90

channels

enum<string>[]

Channels. Validation: sometimes, array. Arrays also accept comma-separated strings.

Channels item. Validation: string; allowed values: email, print, sms, note.

Available options:

email,

print,

sms,

note

metric_mode

enum<string>

Accepted compatibility choice; this implementation computes written_coverage in either mode.

Available options:

written_coverage,

touchpoints_context

active_donor_window_days

integer

Donation-based eligibility window, default730days; affects donor and donor_program audience periods.

Required range: 1 <= x <= 3650

household_mode

enum<string>

Accepted compatibility choice; this implementation continues to project person-level targets.

Available options:

person,

household

assigned_admin_id

integer | null

Assigned admin id. Validation: nullable, integer, min:1.

Required range: x >= 1

include_transactional_context

boolean

Include transactional context. Validation: sometimes, boolean.

include_broadcast_context

boolean

Include broadcast context. Validation: sometimes, boolean.

include_covered

boolean

Include covered. Validation: sometimes, boolean.

unread_only

boolean

Unread only. Validation: sometimes, boolean.

pending_approval_only

boolean

Pending approval only. Validation: sometimes, boolean.

no_thread_only

boolean

No thread only. Validation: sometimes, boolean.

page

integer

Page. Validation: sometimes, integer, min:1.

Required range: x >= 1

per_page

integer

Per page. Validation: sometimes, integer, min:1, max:100.

Required range: 1 <= x <= 100

sort

object

Sort. Validation: sometimes, array.

Show child attributes

Response

Operation result.

data

object

Show child attributes

Read communication coverage target history

curl --request GET \
  --url https://api.gratona.com/v1/admin/communications/coverage/targets/{coverageTargetId} \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.gratona.com/v1/admin/communications/coverage/targets/{coverageTargetId}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.gratona.com/v1/admin/communications/coverage/targets/{coverageTargetId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.gratona.com/v1/admin/communications/coverage/targets/{coverageTargetId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.gratona.com/v1/admin/communications/coverage/targets/{coverageTargetId}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.gratona.com/v1/admin/communications/coverage/targets/{coverageTargetId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "data": {
    "target": {
      "id": 42,
      "client_id": 42,
      "coverage_target_id": 42,
      "donor_entity_id": 42,
      "donor_id": 42,
      "entity_id": 42,
      "program_id": 42,
      "assigned_admin_id": 42,
      "latest_thread_id": 42,
      "target_key": "donor:42",
      "target_type": "sponsorship_pair",
      "basis_type": "commitment",
      "target_status": "active",
      "coverage_status": "never_covered",
      "target_started_at": "2026-10-20 12:00:00",
      "target_ended_at": "2026-10-20 12:00:00",
      "created_at": "2026-10-20 12:00:00",
      "updated_at": "2026-10-20 12:00:00",
      "last_qualifying_touch_at": "2026-10-20 12:00:00",
      "last_any_written_touch_at": "2026-10-20 12:00:00",
      "last_context_only_touch_at": "2026-10-20 12:00:00",
      "latest_inbound_at": "2026-10-20 12:00:00",
      "qualifying_count": 1,
      "context_count": 1,
      "event_count": 1,
      "pending_approval_count": 1,
      "unread_inbound_count": 1,
      "covered_30d": 1,
      "severity": 1,
      "quick_links": {
        "open_donor_url": "/app/view_donor/42",
        "open_recipient_url": "/app/view_donor/42",
        "open_message_manager_url": "/app/view_donor/42",
        "open_coverage_url": "/app/view_donor/42",
        "compose_url": "/app/view_donor/42"
      },
      "has_thread": true,
      "has_conversation_thread": true,
      "latest_inbound_unread": true,
      "latest_thread_status": "<string>",
      "assigned_admin_name": "Example",
      "donor_name": "Example",
      "entity_name": "Example",
      "program_name": "Example",
      "programs_summary": "Example",
      "timeline": [
        "<unknown>"
      ]
    },
    "timeline": [
      {
        "event_at": "2026-10-20T12:00:00Z",
        "source_type": "message_manager",
        "channel": "email",
        "coverage_scope": "recipient_specific",
        "direction": "outbound",
        "delivery_status": "sent",
        "qualifies_for_target": true,
        "label": "Education update"
      }
    ],
    "queue_state": {
      "latest_thread_id": 42,
      "latest_thread_status": "<string>",
      "assigned_admin_id": 42,
      "assigned_admin_name": "Example",
      "unread_inbound_count": 1,
      "pending_approval_count": 1
    },
    "actions": {
      "open_donor_url": "/app/view_donor/42",
      "open_recipient_url": "/app/view_donor/42",
      "open_message_manager_url": "/app/view_donor/42",
      "open_coverage_url": "/app/view_donor/42",
      "compose_url": "/app/view_donor/42"
    }
  }
}

{
  "message": "Unauthorized",
  "status": "error"
}

{
  "message": "Not Found",
  "status": "error"
}

{
  "errors": {},
  "status": "error",
  "message": "The given data was invalid."
}