Skip to content
Pidgely Docs

API reference · Broadcasts

Retrieve a broadcast

GEThttps://api.pidgely.com/broadcasts/{id}
View as Markdown

Retrieves a broadcast with its status (draft, scheduled, queued, sending, sent, canceled or failed), recipients and per-status delivery stats.

Authorization: Bearer pdg_…. An API key with full_access. A sending_access key gets 401 restricted_api_key.

Path parameters

Name Type Required Description
id string Yes Resource id UUID.

Request

Node.js
import { Pidgely } from 'pidgely';

const pidgely = new Pidgely(process.env.PIDGELY_API_KEY);

const { data, error } = await pidgely.broadcasts.get('0199d7f6-4c8d-7e1a-9b3f-2d6a5c0e7f19');
console.log(data ?? error);
Python
import os
import pidgely

pidgely.api_key = os.environ["PIDGELY_API_KEY"]

result = pidgely.Broadcasts.get("0199d7f6-4c8d-7e1a-9b3f-2d6a5c0e7f19")
print(result)
PHP
<?php

require __DIR__ . '/vendor/autoload.php';

$pidgely = Pidgely::client(getenv('PIDGELY_API_KEY'));

$result = $pidgely->broadcasts->get('0199d7f6-4c8d-7e1a-9b3f-2d6a5c0e7f19');
var_dump($result);
Go
package main

import (
	"context"
	"fmt"
	"os"

	"github.com/pidgely/pidgely-go"
)

func main() {
	ctx := context.Background()
	client := pidgely.NewClient(os.Getenv("PIDGELY_API_KEY"))

	result, err := client.Broadcasts.Get(ctx, "0199d7f6-4c8d-7e1a-9b3f-2d6a5c0e7f19")
	if err != nil {
		panic(err)
	}
	fmt.Println(result)
}
Ruby
require "pidgely"

Pidgely.api_key = ENV["PIDGELY_API_KEY"]

result = Pidgely::Broadcasts.get("0199d7f6-4c8d-7e1a-9b3f-2d6a5c0e7f19")
puts result
cURL
curl -X GET 'https://api.pidgely.com/broadcasts/0199d7f6-4c8d-7e1a-9b3f-2d6a5c0e7f19' \
  -H "Authorization: Bearer $PIDGELY_API_KEY"

Response

200 OK

JSON
{
  "object": "broadcast",
  "id": "0199d7f6-4c8d-7e1a-9b3f-2d6a5c0e7f19",
  "name": "October product update",
  "segment_id": "0199d7f5-9a3e-7d4b-a1c2-7e5f0b3d6c48",
  "audience_id": "0199d7f5-9a3e-7d4b-a1c2-7e5f0b3d6c48",
  "from": "Acme <news@acme.com>",
  "subject": "What shipped in October",
  "reply_to": [],
  "preview_text": "Five new features and a faster dashboard",
  "html": "<p>Hi {{{FIRST_NAME|there}}},</p><p>…</p><p><a href=\"{{{PIDGELY_UNSUBSCRIBE_URL}}}\">Unsubscribe</a></p>",
  "text": "",
  "status": "sent",
  "created_at": "2026-10-12 16:44:41.000000+00",
  "scheduled_at": null,
  "sent_at": "2026-10-12 16:44:41.000000+00",
  "topic_id": null,
  "recipients": 1200,
  "stats": {
    "delivered": 1187,
    "bounced": 4,
    "suppressed": 9
  }
}

Response fields

Name Type Required Description
object string No Object type.
id string No Unique id (UUID). UUID.
name string No Display name.
segment_id string | null No Segment the broadcast is sent to.
audience_id string | null No —
from string No —
subject string No Subject line, up to 998 bytes. Required unless a template provides it.
reply_to string[] No Reply-To address or list of addresses.
preview_text string No Preview text shown by mail clients next to the subject (inserted as hidden text at the top of the HTML).
html string No HTML body. html or text is required (unless you send with a template).
text string No —
status string No Current status. One of draft, scheduled, queued, sending, sent, canceled, failed.
created_at string No Timestamp in UTC (2026-10-12 16:44:41.000000+00).
scheduled_at string | null No Timestamp in UTC, or null.
sent_at string | null No Timestamp in UTC, or null.
topic_id null No —
recipients integer No Number of contacts the broadcast was sent to.
stats object (map of integer) No Deliveries by status (Pidgely extension).

Errors

Errors have the shape {"statusCode", "name", "message"}. See Errors for the full list.

Status Name When
401 missing_api_key, restricted_api_key No Authorization: Bearer header, or a sending_access key called an endpoint that needs full_access.
403 invalid_api_key, validation_error The API key is invalid or revoked, or the request is not allowed for this account (unverified domain, plan limit, paused account).
404 not_found The resource does not exist in this account (or the id is not a valid UUID).
422 validation_error A field is missing or invalid; message names it.
429 rate_limit_exceeded Too many requests per second. Wait for Retry-After seconds.