Mailfully logo

List emails

GEThttps://api.mailfully.com/v1/emails

List accepted messages, newest first, with keyset pagination. The read window is bounded by the plan's retention floor (free/starter 30 days, growth 60, scale 90); a supplied from is silently clamped up to that floor. List rows never include message bodies. Requires the send or read:emails scope.

Loading code example
Loading code example

Authorizations

Authorizationstringheaderrequired

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

limitintegerdefault: 25

Maximum rows to return. Default 25, clamped to [1, 100].

Required range: x >= 1, x <= 100
Default: 25
cursorstring

Opaque pagination cursor from a previous response's next_cursor.

status"queued" | "sending" | "sent" | "delivered" | "bounced" | "complained" | "failed" | "canceled" | "reconcile_review" | "held"

Filter by lifecycle status.

Allowed values: "queued" | "sending" | "sent" | "delivered" | "bounced" | "complained" | "failed" | "canceled" | "reconcile_review" | "held"
type"transactional" | "marketing"

Filter by the declared kind of mail. Any other value returns 422 "Invalid type filter."

Allowed values: "transactional" | "marketing"
qstring

Search text, 1 to 200 characters after trimming (otherwise 422). Matches messages whose subject, from address or any to address contains the text, ignoring case, or whose id equals it exactly.

Length: >= 1, <= 200
tagstring

Filter by tag value (the tag name is ignored).

domainstring

Filter by exact recipient domain.

recipientstring

Filter by an exact to address; cc and bcc addresses never match.

fromstring<date-time>

Inclusive lower created_at bound (ISO 8601); clamped up to the retention floor.

tostring<date-time>

Inclusive upper created_at bound (ISO 8601).

Response

application/json

A page of emails.

dataarray<object>required
data.idstringrequired

The message id (a bare ULID, no prefix).

data.toarray<string>required
data.fromstringrequired
data.subjectstringrequired
data.status"queued" | "sending" | "sent" | "delivered" | "bounced" | "complained" | "failed" | "canceled" | "reconcile_review" | "held"required

Message lifecycle status.

  • queued: Accepted and waiting to send, or scheduled for later.
  • sending: Being sent now.
  • sent: Handed off for delivery; no delivery result yet.
  • delivered: The recipient's mail server accepted the message.
  • bounced: The message could not be delivered.
  • complained: The recipient reported the message as spam.
  • failed: The message could not be sent.
  • canceled: Canceled before sending. Terminal.
  • held: Waiting for review before sending. It sends if released, and can be canceled.
  • reconcile_review: The send outcome is unclear and needs a person to check it. Contact contact@mailfully.com with the message id.
Allowed values: "queued" | "sending" | "sent" | "delivered" | "bounced" | "complained" | "failed" | "canceled" | "reconcile_review" | "held"
data.type"transactional" | "marketing"required

The kind of mail, as the sender declares it. Omitting the field means transactional. A marketing send is subject to extra compliance rules — it accepts exactly one recipient across to/cc/bcc, the organization must have a postal address on file, and it draws on a separate monthly marketing allowance.

Allowed values: "transactional" | "marketing"
Default: "transactional"
data.last_eventstringrequired

The message's latest state in status words (delivered, bounced, complained), not the event type names used by /events. Falls back to status.

data.recipient_domainstringrequired
data.tagsarray<object>required
data.created_atstring<date-time>required
data.scheduled_atstring<date-time>required
has_morebooleanrequired
next_cursorstringrequired

Opaque cursor for the next page; pass back as cursor.