# Retrieves a paginated list of events

Mailgun tracks every inbound and outbound message event and retains this data for at least 3 days.
See Filter expression for details about filtering expressions


Endpoint: GET /v3/{domain_name}/events
Version: 3.0.0
Security: basicAuth

## Query parameters:

  - `begin` (string)
    The beginning of the search time range in epoch seconds

  - `end` (string)
    The end of the search time range in epoch seconds

  - `ascending` (string)
    Sort direction by time. Must be provided if the range end time is not specified. Can be either yes or no
    Enum: "yes", "no"

  - `limit` (integer)
    The number of entries to return (300 max)

  - `event` (string)
    Filter by event type

  - `list` (string)
    Filter by mailing list email address that message was originally sent to

  - `attachment` (string)
    Filter by the name of an attached file

  - `from` (string)
    Filter by email address mentioned in the From MIME header

  - `message-id` (string)
    Filter by Mailgun message id returned by the messages API

  - `subject` (string)
    Filter by subject line

  - `to` (string)
    Filter by email address mentioned in the To MIME header

  - `size` (string)
    Filter by message size. Mostly intended to be used with range filtering expressions

  - `recipient` (string)
    Filter by email address of a recipient. While messages are addressable to one or more recipients, each event (with one exception) tracks one recipient. See stored events for use of recipients

  - `recipients` (string)
    Specific to stored events, this field tracks all of the potential message recipients.

  - `tags` (string)
    Filter by user defined tags

  - `severity` (string)
    Filter by event severity, if exists. Currently for failed events only. See Tracking Failures
    Enum: "temporary", "permanent"

## Path parameters:

  - `domain_name` (string, required)
    Filter by sending domain

## Response 200 fields (application/json):

  - `items` (array)

  - `items.method` (string)

  - `items.id` (string)
    GUID identifying the individual event

  - `items.event` (string)
    The event name. See [Events](https://documentation.mailgun.com/docs/mailgun/user-manual/events/#introduction-to-events)
    Enum: "accepted", "delivered", "failed", "rejected", "clicked", "opened", "unsubscribed", "stored", "complained", "email_validation", "list_member_uploaded", "list_member_upload_error", "list_uploaded"

  - `items.timestamp` (number)
    Unix epoch, in nanoseconds, when the event was first created

  - `items.log-level` (string)
    Logging categorization between
    Enum: "info", "warn", "error"

  - `items.flags` (object)

  - `items.flags.is-authenticated` (boolean)
    if it’s an outgoing message.  if it’s incoming.

  - `items.flags.is-routed` (boolean)
    if the message was sent as a result of a Route match

  - `items.flags.is-amp` (boolean)
    Tells if the message has AMP component in

  - `items.flags.is-encrypted` (boolean)
    Tells if the message has been encrypted before stored

  - `items.flags.is-test-mode` (boolean)
    If , the message has been marked as delivered but the actual send stop before sending to the ESP

  - `items.reject` (object)

  - `items.reject.reason` (string)

  - `items.reject.description` (string)

  - `items.message` (object)

  - `items.message.attachments` (array, required)

  - `items.message.attachments.filename` (string, required)
    The name of the file attached to the message

  - `items.message.attachments.content-type` (string, required)
    The type of the content attached to the message

  - `items.message.attachments.size` (integer, required)
    The attachment size in bytes

  - `items.message.headers` (object, required)

  - `items.message.headers.message-id` (string, required)

  - `items.message.headers.from` (string, required)
    Message FROM header

  - `items.message.headers.to` (string)
    Message TO header

  - `items.message.headers.subject` (string)
    Message Subject

  - `items.message.size` (integer, required)
    Total message size, in bytes

  - `items.message.scheduled-for` (string)
    Date/Time the message was scheduled for delivery on ingest

  - `items.tags` (array)

  - `items.user-variables` (object)
    Variables included in the email

  - `items.storage` (object)

  - `items.storage.key` (string)
    Key ID for the stored MIME

  - `items.storage.url` (string)
    URL for the stored MIME for retrieval, if required

  - `items.storage.region` (string)
    The datacenter region the message is stored in

  - `items.geolocation` (object)
    Location data based on the client IP

  - `items.geolocation.country` (string)

  - `items.geolocation.region` (string)

  - `items.geolocation.city` (string)

  - `items.client-info` (object)

  - `items.client-info.client-type` (string)
    Categorize client between: mobile browser, library, email client, robot, feed reader or other

  - `items.client-info.client-os` (string)
    The client Operating System

  - `items.client-info.device-type` (string)
    Could be: desktop, mobile, table or unknown

  - `items.client-info.client-name` (string)
    The client product identifier

  - `items.client-info.user-agent` (string)

  - `items.ip` (string)

  - `items.delivery-status` (object)

  - `items.delivery-status.code` (integer)
    SMTP status code received as a result of the ESP session

  - `items.delivery-status.attempt-no` (integer)
    The current attempt number trying to deliver the message to the ESP

  - `items.delivery-status.enhanced-code` (string)
    A more specific SMTP error code from the ESP

  - `items.delivery-status.mxhost` (string)
    The mailing host connected to for the SMTP session

  - `items.delivery-status.certificate-verified` (boolean)

  - `items.delivery-status.tls` (boolean)
    True if the SMTP session was performed over a TLS connection with the ESP

  - `items.delivery-status.utf8` (boolean)
    True if the SMTP session was able to use UTF-8 encoding

  - `items.delivery-status.first-delivery-attempt-seconds` (number)
    Time elapsed between when the message is accepted by us and the first delivery attempt to the email service provider (ESP)

  - `items.delivery-status.session-seconds` (number)
    The time, in seconds, the SMTP session for this message took

  - `items.delivery-status.retry-seconds` (integer)
    If the message failed for a reason that can be retried, the number of seconds between retry attempts. This value changes as the number of retries grows!

  - `items.batch` (object)

  - `items.batch.id` (string)

  - `items.severity` (string)
    Filter by event severity, if exists. Currently for failed events only. See [Tracking Failures](https://documentation.mailgun.com/docs/mailgun/user-manual/tracking-messages/#tracking-failures)
    Enum: "temporary", "permanent"

  - `items.recipient-domain` (string)
    ESP domain

  - `items.recipient-provider` (string)
    Name of the Inbox Provider for the given recipient, if known

  - `items.template` (object)

  - `items.template.name` (string)
    Name of the template the message was rendered from, if given

  - `items.template.version` (string)
    The version of the template that was rendered

  - `items.template.is-text` (string)
    Tell if the template is considered as plain text (in opposition to ‘html’)

  - `items.envelope` (object)

  - `items.envelope.sender` (string)
    The sender address

  - `items.envelope.targets` (string)
    The recipient address

  - `items.envelope.transport` (string)
    The protocol used to make the send. Either http or smtp

  - `items.envelope.sending-ip` (string)
    The Mailgun IP the email has been sent from

  - `paging` (object)

  - `paging.next` (string)

  - `paging.previous` (string)