# 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) true if it’s an outgoing message. false if it’s incoming. - `items.flags.is-routed` (boolean) true 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 true, 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.message` (string) - `items.delivery-status.description` (string) - `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)