Email Events

Email lifecycle

Every email goes through a series of statuses from the moment you send it:

queued → sending → sent → delivered
                       ↘ bounced
                       ↘ failed

If you set scheduledAt, the email starts in scheduled until the delivery time:

scheduled → queued → sending → sent → delivered

Status	Description
`scheduled`	Email is scheduled for future delivery
`queued`	Email accepted and queued for processing
`sending`	Email is being sent to the mail provider
`sent`	Email handed off to the mail provider
`delivered`	Email accepted by the recipient’s mail server
`bounced`	Email rejected by the recipient’s mail server
`failed`	Email failed to send (provider error, content issue, etc.)

Event types

Each email generates events as it moves through the delivery pipeline:

Event	Description
`queued`	Email accepted into the queue
`sending`	Email picked up for delivery
`sent`	Handed off to mail provider
`delivered`	Successfully delivered to recipient’s inbox
`bounced`	Email bounced (generic bounce event)
`hard_bounce`	Hard bounce — permanent delivery failure
`soft_bounce`	Soft bounce — temporary issue (mailbox full, server down)
`deferred`	Delivery deferred — will be retried
`opened`	Recipient opened the email
`clicked`	Recipient clicked a link in the email
`unsubscribed`	Recipient unsubscribed
`spam_report`	Recipient marked the email as spam
`blocked`	Email blocked by recipient’s server
`failed`	Permanent send failure
`cancelled`	Scheduled email was cancelled before delivery

Get events for an email

Retrieve the full event timeline for a specific email:

curl https://api.mail.gorillaa.one/v1/emails/em_abc123/events \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": [
    {
      "type": "queued",
      "timestamp": "2026-02-09T10:00:00Z"
    },
    {
      "type": "sent",
      "timestamp": "2026-02-09T10:00:02Z"
    },
    {
      "type": "delivered",
      "timestamp": "2026-02-09T10:00:05Z"
    },
    {
      "type": "opened",
      "timestamp": "2026-02-09T10:15:30Z",
      "metadata": {
        "userAgent": "Mozilla/5.0...",
        "ipAddress": "203.0.113.42"
      }
    },
    {
      "type": "clicked",
      "timestamp": "2026-02-09T10:16:12Z",
      "metadata": {
        "url": "https://yourdomain.com/dashboard",
        "userAgent": "Mozilla/5.0..."
      }
    }
  ]
}

Get email details with counts

The email detail response includes delivery status and the full event timeline:

{
  "data": {
    "id": "em_abc123",
    "organizationId": "org_xyz",
    "status": "delivered",
    "fromEmail": "[email protected]",
    "fromName": "Your App",
    "toEmails": ["[email protected]"],
    "ccEmails": [],
    "bccEmails": [],
    "subject": "Your invoice is ready",
    "createdAt": "2026-02-09T10:00:00Z",
    "sentAt": "2026-02-09T10:00:02Z",
    "deliveredAt": "2026-02-09T10:00:05Z",
    "events": [
      { "type": "queued", "timestamp": "2026-02-09T10:00:00Z" },
      { "type": "sent", "timestamp": "2026-02-09T10:00:02Z" },
      { "type": "delivered", "timestamp": "2026-02-09T10:00:05Z" },
      { "type": "opened", "timestamp": "2026-02-09T10:15:30Z" }
    ]
  }
}

Side effects

Some events automatically trigger actions in your account:

Event	Side effect
`hard_bounce`	Recipient added to suppression list
`spam_report`	Recipient added to suppression list
`unsubscribed`	Recipient added to suppression list
`delivered`	Email status updated to `delivered`
`opened`	`openCount` incremented
`clicked`	`clickCount` incremented

Suppressed addresses are automatically skipped on future sends, protecting your sender reputation. See Suppressions for details.

Polling for events

To track an email’s progress, poll the events endpoint:

async function waitForDelivery(emailId, apiKey) {
  const maxAttempts = 10;
  const delayMs = 5000; // 5 seconds

  for (let i = 0; i < maxAttempts; i++) {
    const response = await fetch(
      `https://api.mail.gorillaa.one/v1/emails/${emailId}`,
      { headers: { Authorization: `Bearer ${apiKey}` } }
    );
    const { data: email } = await response.json();

    if (["delivered", "bounced", "failed"].includes(email.status)) {
      return email;
    }

    await new Promise((r) => setTimeout(r, delayMs));
  }

  throw new Error("Timed out waiting for delivery");
}

For high-volume use cases, use the Analytics endpoints instead of polling individual emails.

Get Started

Guides

Reference

Email lifecycle

Event types

Get events for an email

Response

Get email details with counts

Side effects

Polling for events

​Email lifecycle

​Event types

​Get events for an email

​Response

​Get email details with counts

​Side effects

​Polling for events

Email lifecycle

Event types

Get events for an email

Response

Get email details with counts

Side effects

Polling for events