Skip to content
Pidgely Docs

API reference · Emails

List emails

GEThttps://api.pidgely.com/emails
View as Markdown

Lists sent emails, newest first, with cursor pagination. The default page size is 20 (maximum 100).

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

Query parameters

Name Type Required Description
limit integer No Page size (1-100). Between 1 and 100.
after string No Id of the last item of the previous page (older items). UUID.
before string No Id of the first item of the current page (newer items). UUID.
status string No Comma-separated last_event values (queued, scheduled, delivered, delivery_delayed, bounced, complained, suppressed, failed, canceled). Pidgely extension.
to string No Recipient address (exact), or an end date when not an address. Pidgely extension.
q string No Substring of the subject or From. Pidgely extension.
from string No Start date (YYYY-MM-DD or RFC 3339). Alias: since.
since string No —
until string No End date (inclusive day, or RFC 3339 instant).
recipient string No Recipient address (alias of to).

Request

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

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

const { data, error } = await pidgely.emails.list({
  limit: 20,
});
console.log(data ?? error);
Python
import os
import pidgely

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

result = pidgely.Emails.list({
    "limit": 20,
})
print(result)
PHP
<?php

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

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

$result = $pidgely->emails->list([
    'limit' => 20,
]);
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.Emails.List(ctx, &pidgely.ListParams{
		Limit: 20,
	})
	if err != nil {
		panic(err)
	}
	fmt.Println(result)
}
Ruby
require "pidgely"

Pidgely.api_key = ENV["PIDGELY_API_KEY"]

result = Pidgely::Emails.list({
  limit: 20
})
puts result
cURL
curl -X GET 'https://api.pidgely.com/emails?limit=20' \
  -H "Authorization: Bearer $PIDGELY_API_KEY"

Response

200 OK

JSON
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "email",
      "id": "0199d8a2-6f3c-7c51-9e2a-3b1f0c6d4e21",
      "message_id": "<0199d8a2-6f3c-7c51-9e2a-3b1f0c6d4e21@acme.com>",
      "to": [
        "delivered@example.com"
      ],
      "cc": [],
      "bcc": [],
      "reply_to": [],
      "from": "Acme <onboarding@acme.com>",
      "subject": "Welcome to Acme",
      "html": "<p>Thanks for signing up!</p>",
      "text": "Thanks for signing up!",
      "created_at": "2026-10-12 16:44:41.000000+00",
      "scheduled_at": null,
      "last_event": "delivered",
      "tags": [
        {
          "name": "category",
          "value": "welcome"
        }
      ]
    }
  ]
}

Response fields

Name Type Required Description
object string Yes Object type. One of list.
has_more boolean Yes Whether another page exists.
data object[] Yes Items of this page.
data[].object string No Object type.
data[].id string No Unique id (UUID). UUID.
data[].message_id string No Message-ID header of the email.
data[].to string[] No Recipient address (a@x.com or Name <a@x.com>) or a list of them. Up to 50 unique recipients across to, cc and bcc.
data[].cc string[] No Carbon-copy recipients. Count toward the 50-recipient limit.
data[].bcc string[] No Blind carbon-copy recipients. Count toward the 50-recipient limit.
data[].reply_to string[] No Reply-To address or list of addresses.
data[].from string No —
data[].subject string No Subject line, up to 998 bytes. Required unless a template provides it.
data[].html string | null No HTML body. html or text is required (unless you send with a template).
data[].text string | null No —
data[].created_at string No Timestamp in UTC (2026-10-12 16:44:41.000000+00).
data[].scheduled_at string | null No Timestamp in UTC, or null.
data[].last_event string No Most advanced status across the recipients. One of queued, scheduled, sent, delivered, delivery_delayed, bounced, complained, suppressed, failed, canceled.
data[].tags object[] No Name/value pairs attached to the email and returned in webhooks.
data[].tags[].name string Yes Display name. Pattern: ^[A-Za-z0-9_-]{1,256}$.
data[].tags[].value string Yes Pattern: ^[A-Za-z0-9_-]{1,256}$.

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.