Get an email

GET/email/v1/emails/{id}

Returns an email by its id, with its status now and everything that happened to it. Any of your team's emails, sent with the API or from the app.

Path parameters

• #idstring (uuid)Required
  The email id returned by POST /emails.
  Example: 3f0e8a52-6f4b-4d0e-9b8a-2c1d0e9f8a7b

Events

events lists what happened to the email, oldest first. Each has a type, the time it happened (at), and a detail: why it bounced or failed, when it did, and otherwise null.

An event's type is one of the statuses. OPENED and CLICKED are kept for open and click tracking, which isn't on yet. Ignore a type you don't recognise.

Waiting for delivery

Most emails are DELIVERED within a minute. If you poll, wait 30 to 60 seconds between calls. A webhook tells you as each thing happens.

Example request

curl

curl "https://sandbox-api.ponitor.com/email/v1/emails/3f0e8a52-6f4b-4d0e-9b8a-2c1d0e9f8a7b" \
  -H "apiKey: $PONITOR_API_KEY"

Node.js

const response = await fetch('https://sandbox-api.ponitor.com/email/v1/emails/3f0e8a52-6f4b-4d0e-9b8a-2c1d0e9f8a7b', {
  headers: { apiKey: process.env.PONITOR_API_KEY },
});

console.log(response.status, await response.json());

Python

import os

import requests

response = requests.get(
    "https://sandbox-api.ponitor.com/email/v1/emails/3f0e8a52-6f4b-4d0e-9b8a-2c1d0e9f8a7b",
    headers={"apiKey": os.environ["PONITOR_API_KEY"]},
    timeout=30,
)
print(response.status_code, response.json())

PHP

<?php

$ch = curl_init('https://sandbox-api.ponitor.com/email/v1/emails/3f0e8a52-6f4b-4d0e-9b8a-2c1d0e9f8a7b');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['apiKey: ' . getenv('PONITOR_API_KEY')],
]);

$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
echo $status, ' ', $body, PHP_EOL;

Responses

200

OK. The email object, with its status now and its events.

{
  "id": "3f0e8a52-6f4b-4d0e-9b8a-2c1d0e9f8a7b",
  "externalId": "signup-8812",
  "from": "\"Example\" <hello@mail.example.com>",
  "to": "ada@example.com",
  "subject": "Your code is 482913",
  "templateName": "Verification Code",
  "status": "DELIVERED",
  "cost": 0.002,
  "refunded": false,
  "failureReason": null,
  "createdAt": "2026-11-02T12:00:00.000Z",
  "sentAt": "2026-11-02T12:00:02.000Z",
  "events": [
    { "type": "QUEUED", "at": "2026-11-02T12:00:00.000Z", "detail": null },
    { "type": "SENT", "at": "2026-11-02T12:00:02.000Z", "detail": null },
    { "type": "DELIVERED", "at": "2026-11-02T12:00:04.000Z", "detail": null }
  ]
}

400

Bad Request. id is not a valid UUID (E01001). Every error has an error object. See The error body.

401

Unauthorized. The API key is missing (E02001), wrong or revoked (E02002), or sent to the other base URL (E02003). See API keys and base URLs.

404

Not Found. No email with that id belongs to your team (E01005).

{
  "error": {
    "type": "not_found_error",
    "code": "E01005",
    "name": "NotFound",
    "message": "Email not found.",
    "doc_url": "https://docs.ponitor.com/api/errors#E01005",
    "request_id": "4a5b6c7d-8e9f-4a0b-8c1d-2e3f4a5b6c7d"
  }
}

429

Too Many Requests. Your team went over its rate limit (E01011). Wait, then try again.