EmailListItem

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/groundmail-dev/json-schema/groundmail-dev-email-list-item-schema.json",
  "title": "EmailListItem",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/groundmail-dev-openapi.yaml#/components/schemas/EmailListItem",
  "type": "object",
  "required": [
    "id",
    "from",
    "to",
    "subject",
    "status",
    "created_at"
  ],
  "properties": {
    "id": {
      "type": "string"
    },
    "from": {
      "type": "string"
    },
    "to": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "email"
      }
    },
    "cc": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "email"
      }
    },
    "bcc": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "email"
      }
    },
    "reply_to": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "email"
      }
    },
    "subject": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": [
        "queued",
        "scheduled",
        "sent",
        "delivered",
        "delayed",
        "held",
        "opened",
        "clicked",
        "bounced",
        "complained",
        "failed",
        "suppressed",
        "cancelled"
      ],
      "description": "`queued`: accepted and stored, not yet handed to the mail server; it moves on within moments (or `failed`, with `bounce_reason`, if the mail server refuses it). `held`: stopped before sending. Content scanning held it for review (it is then sent or rejected, and you get `email.delivered` or `email.failed`), or sending is paused on the account and it goes out when sending resumes."
    },
    "last_event": {
      "type": [
        "string",
        "null"
      ]
    },
    "bounce_reason": {
      "type": [
        "string",
        "null"
      ]
    },
    "bounce_type": {
      "$ref": "#/$defs/BounceType"
    },
    "delivery": {
      "allOf": [
        {
          "$ref": "#/$defs/EmailDelivery"
        }
      ],
      "nullable": true,
      "description": "The receiving server's side of the latest delivery attempt: which server took the email, its exact reply, whether the connection used TLS, and the latest deferral. Null until an attempt reports one, and for test emails."
    },
    "held_back": {
      "type": "array",
      "description": "Recipients Groundmail validation held back before sending; empty when none were.",
      "items": {
        "$ref": "#/$defs/HeldBackRecipient"
      }
    },
    "test": {
      "type": "boolean",
      "description": "`true` when the email never reached the mail server: it was sent with a test key (`gm_test_…`) or only to simulator addresses. Its status and events are simulated, and it is not counted in stats or billing.\n"
    },
    "stream": {
      "$ref": "#/$defs/MailStream"
    },
    "tenant": {
      "type": [
        "string",
        "null"
      ],
      "description": "The `external_id` of the tenant the email was sent for. Present only on tenant email (`null` once that tenant is deleted).\n"
    },
    "tags": {
      "oneOf": [
        {
          "type": "array",
          "items": {
            "$ref": "#/$defs/EmailTag"
          }
        },
        {
          "type": "object"
        }
      ],
      "nullable": true
    },
    "scheduled_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "cancelled_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "sent_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "delivered_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "bounced_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "opened_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "First time a recipient opened the email. Requires open tracking on the sending domain."
    },
    "clicked_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "First time a recipient clicked a tracked link. Requires click tracking on the sending domain."
    }
  },
  "$defs": {
    "BounceType": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "hard",
        "block"
      ],
      "description": "Why the email bounced. Null when it has not bounced (and for complaints).\n\n- `hard`: the address cannot receive mail (unknown user, disabled mailbox,\n  domain with no mail server). The address is added to your suppression list.\n- `block`: the receiving server refused the message because of the sending\n  IP's or domain's reputation or policy, for example a blocklist listing or a\n  mailbox provider's spam policy. The address is fine and is not suppressed,\n  and block bounces do not count toward your bounce rate. You can send to it\n  again later.\n\nPresent on `email.bounced` and `email.failed` webhook events and on the email\nobject. Treat unknown future values like `hard`.\n"
    },
    "EmailDelivery": {
      "type": "object",
      "required": [
        "receiving_server",
        "response",
        "tls",
        "deferred_response",
        "deferred_at"
      ],
      "description": "What the recipient's mail server said about the latest delivery attempt.\n\n- On delivery, `response` is its acceptance reply (a `250`), and `delivered_at`\n  minus `created_at` is how long the email took to land.\n- On a refusal, `response` is the reply it refused with (a `5xx`), the same\n  text that leads `bounce_reason`.\n- A deferral (a `4xx`, such as greylisting) sets `deferred_response` and\n  `deferred_at`. Delivery is retried automatically, and the deferral stays here\n  after the email is delivered.\n",
      "properties": {
        "receiving_server": {
          "type": [
            "string",
            "null"
          ],
          "description": "Hostname of the recipient's mail server that took the connection."
        },
        "response": {
          "type": [
            "string",
            "null"
          ],
          "description": "Its SMTP reply to the latest attempt that finished, exactly as sent (a multi-line reply is joined into one line). Null while there has been none."
        },
        "tls": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "Whether the connection used TLS. Null when the attempt didn't say."
        },
        "deferred_response": {
          "type": [
            "string",
            "null"
          ],
          "description": "Its reply to the latest deferral. Null when there was none, or it gave no reply."
        },
        "deferred_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "description": "When the latest deferral happened."
        }
      }
    },
    "EmailTag": {
      "type": "object",
      "required": [
        "name",
        "value"
      ],
      "properties": {
        "name": {
          "type": "string"
        },
        "value": {
          "type": "string"
        }
      }
    },
    "HeldBackRecipient": {
      "type": "object",
      "required": [
        "email",
        "reason"
      ],
      "description": "A recipient Groundmail validation held back before sending.",
      "properties": {
        "email": {
          "type": "string",
          "description": "The held-back address (trimmed, lowercased)"
        },
        "reason": {
          "type": "string",
          "enum": [
            "invalid_address",
            "no_mail_server",
            "previously_bounced",
            "mailbox_not_found"
          ],
          "description": "`invalid_address`: the address cannot exist. `no_mail_server`: the domain does not exist or takes no email (no MX or A record, or a null MX). `previously_bounced`: the address hard-bounced (mailbox does not exist) for a Groundmail sender in the last 90 days. `mailbox_not_found`: Groundmail validation already knows the mailbox does not exist. The last two can be turned off per account in Settings → Suppressions.\n"
        }
      }
    },
    "MailStream": {
      "type": "string",
      "enum": [
        "transactional",
        "product",
        "newsletter"
      ],
      "description": "The mail stream an email went out on, from its `category`. Each stream sends\nfrom its own IPs. `newsletter` is for approved accounts only.\n"
    }
  }
}