Как получить список SendGrid Single Send с названиями через API

Показываем, как получить полный список кампаний SendGrid Single Send с понятными названиями через эндпоинт /v3/marketing/singlesends и пагинацию _metadata.next.

Когда нужен аккуратный список всех кампаний SendGrid Single Send с понятными для человека названиями, легко уйти к «не тому» разделу API. Эндпоинты статистики возвращают подробные данные на уровне сообщений, но так и не сообщают, к какому Single Send эти сообщения относятся по названию. Ниже — как получить именно тот набор данных, который вам нужен, без догадок.

Воспроизводим несоответствие

Получить данные по сообщениям через SendGrid API несложно, но названия Single Send там не отображаются. Короткий пример показывает этот пробел.

import sendgrid
import json
import os

sg_client = sendgrid.SendGridAPIClient(os.environ.get('SENDGRID_API_KEY'))
msg_resp = sg_client.client.messages.get()
data_obj = json.loads(msg_resp.body)
print(json.dumps(data_obj, indent=4))

Ответ содержит только поля уровня сообщения — получателя, статус и т. п. — но без названий кампаний Single Send.

{
    "messages": [
        {
            "from_email": "email@example.com",
            "msg_id": "some-message-id-here1",
            "subject": "Message subject here",
            "to_email": "madeline@example.com",
            "status": "processing",
            "opens_count": 0,
            "clicks_count": 0,
            "last_event_time": "2025-05-14T12:00:10Z"
        },
        {
            "from_email": "email@example.com",
            "msg_id": "some-message-id-here2",
            "subject": "Message subject here",
            "to_email": "theo@example.com",
            "status": "delivered",
            "opens_count": 1,
            "clicks_count": 0,
            "last_event_time": "2025-05-14T12:00:08Z"
        }
    ]
}

Почему названия не видны

Эндпоинт статистики /v3/marketing/stats/singlesends сосредоточен на метриках вовлеченности и доставки. Он создан для анализа эффективности и агрегирует данные на уровне сообщений. Поэтому названий Single Send в выдаче нет. Существует и эндпоинт статистики по конкретному Single Send по ID, но он полезен лишь тогда, когда нужный ID у вас уже есть и вы хотите запрашивать статистику именно по нему.

Правильный эндпоинт для списка Single Send и их названий

Чтобы получить перечень кампаний вместе с названиями, используйте маркетинговый ресурс со списком Single Send: эндпоинт /v3/marketing/singlesends. Сервер возвращает до 100 элементов на страницу и, если данных больше, отдает ссылку на следующую страницу в _metadata.next.

{
    "result": [
        {
            "id": "some_long_id_1",
            "name": "Name of Single Send 1",
            "status": "draft",
            "categories": [],
            "send_at": null,
            "created_at": "2025-05-14T11:00:00Z",
            "updated_at": "2025-05-14T11:30:00Z",
            "is_abtest": false,
            "abtest": null
        },
        {
            "id": "some_long_id_2",
            "name": "Name of Single Send 2",
            "status": "triggered",
            "categories": [],
            "send_at": "2025-05-10T12:00:00Z",
            "created_at": "2025-05-05T12:00:00Z",
            "updated_at": "2025-05-07T12:00:00Z",
            "is_abtest": false,
            "abtest": null
        }
    ],
    "_metadata": {
        "self": "https://api.sendgrid.com/v3/marketing/singlesends?page_token=SOME_TOKEN_HERE_1",
        "next": "https://api.sendgrid.com/v3/marketing/singlesends?page_token=SOME_TOKEN_HERE_2",
        "count": 159
    }
}

Решение: забрать все Single Send с пагинацией

Чтобы собрать полный набор кампаний Single Send и их названий, делайте запрос к /v3/marketing/singlesends и переходите по _metadata.next, пока ссылка присутствует. Пример на Python ниже выгружает все страницы и выводит сводный список.

import requests
import os
import json

auth_hdrs = {"Authorization": f"Bearer {os.environ.get('SENDGRID_API_KEY')}"}
singlesend_catalog = []
page_url = 'https://api.sendgrid.com/v3/marketing/singlesends'

while True:
    http_res = requests.get(page_url, headers=auth_hdrs)
    payload = http_res.json()

    singlesend_catalog.extend(payload.get('result', []))

    next_url = payload.get("_metadata").get("next")
    if next_url:
        page_url = next_url
    else:
        break

print(json.dumps(singlesend_catalog, indent=2))

Почему это важно

Правильный выбор эндпоинта экономит часы работы. Если ваша задача — инвентаризация и названия: аудит кампаний, сопоставление ID с понятными ярлыками или показ операторам удобных списков — ресурсы статистики не дадут нужных полей. А вот маркетинговый список — да: стабильная модель пагинации через _metadata.next и лимит 100 элементов на страницу. Это делает его надежным для полных выгрузок и задач синхронизации.

Выводы

Нужны названия Single Send — вызывайте /v3/marketing/singlesends и переходите по _metadata.next до конца. Эндпоинты статистики применяйте только тогда, когда действительно требуется аналитика по ID или отдельным сообщениям. Разделяя эти роли, вы упрощаете интеграцию и сохраняете чистую модель данных.