# Fetch events (no webhook address needed)

HTML: https://www.app2email.com/docs/api/webhooks/list-events · Index: https://www.app2email.com/docs/api/llms.txt

`GET https://api.app2email.com/v1/{number}/events` · scope `messages:read` · MCP tool `list_events`

The number's events, fetched instead of pushed: for an agent or a script with no public address for a webhook. Every event is the JSON a webhook gets (https://www.app2email.com/docs/api/webhooks), with the same id, oldest first. Keep the `cursor` of each answer and pass it as `after` on the next call; after a lost answer the same event can come again, so skip ids you have handled. `wait` holds the answer until an event arrives (long polling; one waiting call at a time is enough). The first call switches the number's feed on: events are kept from then on, for 72 hours (the newest 2,000), and the feed switches itself off after 7 days without a call. Webhooks keep working beside it.

```shell
curl "https://api.app2email.com/v1/YOUR_NUMBER/events" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## OpenAPI

```json
{
  "/v1/{number}/events": {
    "get": {
      "tags": [
        "Webhooks"
      ],
      "operationId": "listEvents",
      "summary": "Fetch events (no webhook address needed)",
      "description": "The number's events, fetched instead of pushed: for an agent or a script with no public address for a webhook. Every event is the JSON a webhook gets (https://www.app2email.com/docs/api/webhooks), with the same id, oldest first. Keep the `cursor` of each answer and pass it as `after` on the next call; after a lost answer the same event can come again, so skip ids you have handled. `wait` holds the answer until an event arrives (long polling; one waiting call at a time is enough). The first call switches the number's feed on: events are kept from then on, for 72 hours (the newest 2,000), and the feed switches itself off after 7 days without a call. Webhooks keep working beside it.",
      "parameters": [
        {
          "$ref": "#/components/parameters/Number"
        },
        {
          "name": "after",
          "in": "query",
          "required": false,
          "description": "The `cursor` of the previous answer, unchanged. Left out: from the oldest event still kept. `now`: only events from this moment on.",
          "schema": {
            "type": "string",
            "example": "ec_184467"
          }
        },
        {
          "name": "wait",
          "in": "query",
          "required": false,
          "description": "Seconds to wait for an event when there is none yet (0 to 25). 0, the default, answers at once.",
          "schema": {
            "type": "integer",
            "minimum": 0,
            "maximum": 25,
            "default": 0
          }
        },
        {
          "name": "types",
          "in": "query",
          "required": false,
          "description": "Only these event types, comma separated. Left out: every event.",
          "schema": {
            "type": "string",
            "example": "message.received,message.status"
          }
        },
        {
          "name": "from",
          "in": "query",
          "required": false,
          "description": "Only events of this contact (data.from, data.to, data.contact or data.number): full number, digits, with country code.",
          "schema": {
            "type": "string",
            "example": "61412345678"
          }
        },
        {
          "name": "limit",
          "in": "query",
          "required": false,
          "description": "How many (1 to 100).",
          "schema": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100,
            "default": 50
          }
        }
      ],
      "responses": {
        "200": {
          "description": "The events after the cursor (an empty list when there are none).",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EventFeedResponse"
              },
              "example": {
                "success": true,
                "request_id": "e7fd2",
                "events": [
                  {
                    "id": "evt_Xq3k9m2Lw8Rt5Yp1Zs01",
                    "type": "message.status",
                    "created": "2026-11-15T03:10:02.000Z",
                    "number": "4976659348270",
                    "data": {
                      "message_id": "wamid.HBgLNjE0MTIzNDU2NzgVAgARGBI5QTNDQTVCM0Q0Q0Q2RTY3RTcA",
                      "to": "61412345678",
                      "status": "delivered",
                      "timestamp": "2026-11-15T03:10:01.000Z",
                      "sent_by": "api"
                    }
                  },
                  {
                    "id": "evt_Ab7c2d9Ef4Gh6Jk8Lm03",
                    "type": "message.received",
                    "created": "2026-11-15T03:10:09.000Z",
                    "number": "4976659348270",
                    "data": {
                      "message_id": "wamid.HBgLNjE0MTIzNDU2NzgVAgASGBQzQUZCMTY0MDc2MUYwNzBDNTY5MAA=",
                      "from": "61412345678",
                      "name": "John",
                      "type": "text",
                      "text": "Thanks! When will it arrive?",
                      "timestamp": "2026-11-15T03:10:08.000Z"
                    }
                  }
                ],
                "count": 2,
                "cursor": "ec_184467",
                "has_more": false,
                "feed": {
                  "on": true,
                  "started": false,
                  "kept_hours": 72,
                  "waited": true
                }
              }
            }
          }
        },
        "400": {
          "description": "The request is malformed (missing or invalid fields, query parameters or times). Possible error.code values: invalid_number_in_url, invalid_json, unsupported_message_type, invalid_to, too_many_recipients, missing_template_name, missing_template_language, invalid_components, to_and_recipients, invalid_recipients, duplicate_recipients, invalid_idempotency_key, missing_message_id, invalid_number, missing_numbers, too_many_numbers, invalid_numbers, missing_url, invalid_events, too_many_webhooks, invalid_template_name, invalid_template_language, invalid_template_category, invalid_template_components, invalid_reply_to, free_form_single_recipient, missing_text, invalid_text, invalid_send_at, send_at_in_past, send_at_too_far, invalid_time, invalid_limit, invalid_cursor, invalid_direction, invalid_status, invalid_phone, invalid_range, range_too_large, invalid_months, invalid_media_type, missing_file, missing_media, nothing_to_change, invalid_setting, segment_and_recipients, segment_empty, invalid_owner, invalid_contacts, invalid_segment, invalid_csv, too_many_segments, missing_interactive, invalid_interactive, invalid_test_event, invalid_keep_old_for_hours, invalid_contact_email, invalid_plan, invalid_key_request, invalid_estimate, invalid_analytics_query, invalid_conversion_events, invalid_booking, invalid_service, invalid_start, invalid_answers, invalid_addons, invalid_guests, invalid_series, invalid_block, invalid_note, invalid_link, invalid_slug, invalid_call_settings, invalid_call_request, invalid_wait, invalid_event_type, invalid_flow_id, invalid_flow_name, invalid_flow_categories, invalid_flow_json, invalid_flow_field, invalid_public_key, invalid_media_id, invalid_location, invalid_contacts_message, invalid_reaction, invalid_callback_data, caption_not_supported, invalid_marketing_api, invalid_users, invalid_bsuid, invalid_identity_key_hash, invalid_profile, invalid_display_name, invalid_oba_request, invalid_compliance_info, invalid_username, invalid_conversation_starters, invalid_qr_code, invalid_catalog_id, invalid_client_request, invalid_onboarding_request, invalid_redirect_url, invalid_partner_settings, invalid_payment, invalid_coupon, invalid_poll, shop_invalid, invalid_form, invalid_submission, invalid_automation, invalid_connection, invalid_member, invalid_list, invalid_setup, invalid_settings, template_language_required, invalid_template_field, invalid_optimization_spec, invalid_template_ids, too_many_templates, invalid_compare_days, invalid_auth_template, invalid_template_preview, invalid_library_filter, template_insights_confirm_required, invalid_insights_request, invalid_ticket_event, invalid_ticket_order, invalid_ticket_code, invalid_ticket_check_in, invalid_webhook_headers, invalid_webhook_format, invalid_webhook_secret, too_many_catchers.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              }
            }
          }
        },
        "401": {
          "description": "Missing, invalid, revoked or expired API key. Possible error.code values: missing_api_key, invalid_authorization_header, invalid_api_key, api_key_old_format, api_key_revoked, api_key_expired.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              }
            }
          }
        },
        "403": {
          "description": "The key is valid but this call is not allowed: the key lacks the scope the call needs (insufficient_scope), the address is not allowed for the key (ip_not_allowed), the number or plan does not allow it, a recipient opted out or is not opted in, or a problem with the WhatsApp account. Possible error.code values: api_key_number_mismatch, insufficient_scope, ip_not_allowed, plan_not_allowed, service_not_live, recipient_opted_out, recipient_not_opted_in, template_name_reserved, whatsapp_payment_issue, whatsapp_account_locked, whatsapp_account_restricted, sandbox_key, recipient_stopped_marketing, messaging_limit_restricted, display_name_not_approved, username_not_eligible, account_not_confirmed, account_deactivated, booking_not_enabled, link_not_usable, call_permission_required, not_in_instant_sandbox, flow_blocked_by_integrity, whatsapp_permission_missing, partner_suspended, partner_closed, client_not_editable, shop_not_enabled, submit_not_enabled, tickets_not_enabled.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              }
            }
          }
        },
        "404": {
          "description": "The number, template, message, broadcast, webhook, delivery, opt-in, logged request, booking or Flow was not found. Possible error.code values: number_not_found, template_not_found, template_language_not_found, message_not_found, broadcast_not_found, webhook_not_found, delivery_not_found, optin_not_found, request_not_found, conversation_not_found, contact_not_found, segment_not_found, approval_not_found, media_not_found, route_not_found, key_not_found, dataset_not_found, waitlist_not_found, booking_not_found, block_not_found, note_not_found, link_not_found, hold_not_found, flow_not_found, flow_json_not_found, qr_code_not_found, client_not_found, payment_not_found, package_not_found, poll_not_found, shop_not_found, form_not_found, submission_not_found, automation_not_found, connection_not_found, member_not_found, list_not_found, ticket_event_not_found, ticket_date_not_found, ticket_type_not_found, ticket_order_not_found, ticket_not_found, ticket_code_not_found, ticket_check_in_not_found, catcher_not_found.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              }
            }
          }
        },
        "429": {
          "description": "A monthly plan limit, the number's own monthly cap, the key's daily cap, a WhatsApp rate limit, the API rate limit (rate_limited), or the webhook test limit (too_many_tests) was reached. Retry-After and error.retry_after_seconds say how long to wait. Possible error.code values: monthly_limit_reached, too_many_messages_to_recipient, whatsapp_rate_limit, rate_limited, daily_cap_reached, monthly_cap_reached, too_many_tests, register_limit_reached, too_many_signups, media_lookups_paused, too_many_invites.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              }
            }
          }
        },
        "500": {
          "description": "Unexpected error on app2email's side. Possible error.code values: internal_error, background_start_failed, schedule_failed, shop_failed.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ErrorResponse"
              }
            }
          }
        }
      },
      "x-a2e-scope": "messages:read",
      "x-a2e-sandbox": "read",
      "x-a2e-error-codes": [
        "api_key_expired",
        "api_key_number_mismatch",
        "api_key_old_format",
        "api_key_revoked",
        "insufficient_scope",
        "internal_error",
        "invalid_api_key",
        "invalid_authorization_header",
        "invalid_cursor",
        "invalid_event_type",
        "invalid_limit",
        "invalid_number_in_url",
        "invalid_wait",
        "ip_not_allowed",
        "missing_api_key",
        "number_not_found",
        "plan_not_allowed",
        "rate_limited",
        "service_not_live"
      ],
      "x-a2e-webhook-events": [],
      "x-a2e-mcp-tool": "list_events",
      "x-a2e-mcp-tools": [
        "list_events",
        "wait_for_message"
      ],
      "x-a2e-needs": null
    }
  }
}
```
