Gorillaa Mail

https://docs.gorillaa.one
Admin
Gorillaa Mail is a transactional email API for developers that enables sending emails, managing...
Tokens:99,092
Snippets:464
Trust Score:2.5
Update:8 months ago
Show doc for...
Tokens:
Raw
### List All Domains (Bash)

Source: https://docs.gorillaa.one/guides/domains

This bash command retrieves a list of all domains associated with the account by making a GET request to the /v1/domains endpoint. The response includes an array of domain objects and the total count of domains.

```bash
curl https://api.mail.gorillaa.one/v1/domains \
  -H "Authorization: Bearer YOUR_API_KEY"
```

--------------------------------

### Send Email Request Examples (OpenAPI)

Source: https://docs.gorillaa.one/api-reference/emails/send-a-single-email

Examples of sending emails using the Gorillaa Mail API, demonstrating text, HTML, and scheduled email formats. These examples are defined within the OpenAPI specification.

```yaml
openapi: 3.1.0
info:
  title: Gorillaa Mail API
  version: 1.0.0
  description: >
    Gorillaa Mail is a transactional email API service. Send emails, manage
    domains,

    track delivery analytics, handle suppressions, and comply with GDPR/privacy
    regulations.


    ## Authentication

    All `/v1/*` endpoints require a Bearer API key in the `Authorization`
    header:

    ```

    Authorization: Bearer grl_live_xxxxxxxxxxxx

    ```

    API keys are scoped — each key is granted specific permissions (e.g. 
    `email:send`, `domain:read`).


    ## Test Mode

    API keys prefixed with `grl_test_` operate in test mode with reduced limits.

    Test mode responses include `X-Gorillaa-Test-Mode: true` header.


    ## Rate Limiting

    All authenticated endpoints return rate limit headers:

    - `X-RateLimit-Limit` — max requests in window

    - `X-RateLimit-Remaining` — remaining requests

    - `X-RateLimit-Reset` — UTC epoch when window resets


    ## Idempotency

    The `POST /v1/emails` endpoint supports idempotency via the
    `X-Idempotency-Key` header.

    Repeat requests with the same key within 24 hours return the original
    response.


    ## Pagination

    List endpoints use page-based pagination (`page` + `limit`) or offset-based
    (`offset` + `limit`).
  contact:
    name: Gorillaa Mail Support
    url: https://gorillaa.one
    email: support@gorillaa.one
  license:
    name: Proprietary
    url: https://gorillaa.one/terms
servers:
  - url: https://api.mail.gorillaa.one
    description: Production
  - url: http://localhost:8787
    description: Local development
security:
  - BearerApiKey: []
tags:
  - name: Emails
    description: Send, list, and inspect transactional emails
  - name: Domains
    description: Register, verify, and manage sender domains
  - name: Statistics
    description: Delivery analytics, domain breakdown, and reputation metrics
  - name: Suppressions
    description: Manage suppressed/bounced email addresses
  - name: Privacy
    description: GDPR-compliant data export, erasure, and privacy preferences
  - name: GDPR
    description: Data Subject Request operations (Art. 15 export, Art. 17 erasure)
  - name: Health
    description: Service health and readiness probes
paths:
  /v1/emails:
    post:
      tags:
        - Emails
      summary: Send a single email
      description: >
        Queue a single email for delivery. Returns immediately with a `queued`
        or `scheduled` status.


        Requires `email:send` scope.


        Supports idempotency via the `X-Idempotency-Key` header — duplicate
        requests within 24h

        return the original response.


        Either `html` or `text` body is required. Total recipients (to + cc + 
        bcc) cannot exceed 50.
      operationId: sendEmail
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendEmailRequest'
            examples:
              simple:
                summary: Simple text email
                value:
                  from: hello@yourdomain.com
                  to:
                    - user@example.com
                  subject: Welcome!
                  text: Thanks for signing up.
              rich:
                summary: HTML email with metadata
                value:
                  from:
                    email: noreply@yourdomain.com
                    name: Gorillaa Mail
                  to:
                    - email: user@example.com
                      name: Jane Doe
                  subject: Your invoice is ready
                  html: '<h1>Invoice #1234</h1><p>Amount: $99.00</p>'
                  tags:
                    - invoice
                    - billing
                  metadata:
                    invoiceId: '1234'
                    userId: usr_abc
              scheduled:
                summary: Scheduled email
                value:
                  from: hello@yourdomain.com
                  to:
                    - user@example.com
                  subject: Reminder
                  text: Don't forget your meeting tomorrow.
                  scheduledAt: '2026-02-10T09:00:00Z'
      responses:
        '202':
          description: Email accepted for delivery
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/SendEmailResponse'
                required:
                  - data
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:

```

--------------------------------

### Add Domain API Response (JSON)

Source: https://docs.gorillaa.one/guides/domains

This is an example JSON response after successfully adding a domain. It includes the domain's unique ID, verification status, DKIM selector, and the specific DNS records (type, host, value) that need to be configured at your DNS provider.

```json
{
  "data": {
    "id": "dom_abc123",
    "domain": "yourdomain.com",
    "subdomain": null,
    "verification_status": "pending",
    "verified_at": null,
    "dkim_selector": "gorillaa",
    "dkim_status": null,
    "warming_status": "not_started",
    "warming_current_limit": null,
    "reputation_score": null,
    "is_default": false,
    "records": [
      {
        "type": "TXT",
        "host": "_gorillaa-verify.yourdomain.com",
        "value": "gorillaa-verify=a1b2c3d4e5f6...",
        "priority": null,
        "purpose": "verification",
        "verified": false
      },
      {
        "type": "CNAME",
        "host": "gorillaa._domainkey.yourdomain.com",
        "value": "gorillaa._domainkey.yourdomain.com.mail.gorillaa.one",
        "priority": null,
        "purpose": "dkim",
        "verified": false
      },
      {
        "type": "TXT",
        "host": "yourdomain.com",
        "value": "v=spf1 include:_spf.mail.gorillaa.one ~all",
        "priority": null,
        "purpose": "spf",
        "verified": false
      },
      {
        "type": "TXT",
        "host": "_dmarc.yourdomain.com",
        "value": "v=DMARC1; p=none; rua=mailto:dmarc@yourdomain.com",
        "priority": null,
        "purpose": "dmarc",
        "verified": false
      }
    ],
    "created_at": "2026-02-09T12:00:00Z",
    "updated_at": "2026-02-09T12:00:00Z"
  }
}
```

--------------------------------

### API Key Authentication Example

Source: https://docs.gorillaa.one/api-reference/domains/trigger-dns-verification

This example shows how to authenticate API requests using a Bearer token with your Gorillaa Mail API key. Test keys start with 'grl_test_' and live keys with 'grl_live_'.

```http
Authorization: Bearer grl_live_xxxxxxxxxxxx
```

--------------------------------

### Get Email Status

Source: https://docs.gorillaa.one/quickstart

Check the status of a previously sent email using its unique identifier.

```APIDOC
## GET /v1/emails/{email_id}

### Description
Retrieve the status of a specific email.

### Method
GET

### Endpoint
https://api.mail.gorillaa.one/v1/emails/{email_id}

### Parameters
#### Path Parameters
- **email_id** (string) - Required - The unique identifier of the email.

#### Headers
- **Authorization** (string) - Required - Bearer token for authentication.

### Response
#### Success Response (200)
- **data** (object) - Contains details about the email status.
  - **id** (string) - The unique identifier for the email.
  - **status** (string) - The current status of the email.

#### Response Example
```json
{
  "data": {
    "id": "em_abc123",
    "status": "delivered"
  }
}
```
```

--------------------------------

### Not Found Error Response Example

Source: https://docs.gorillaa.one/api-reference/domains/trigger-dns-verification

This JSON example illustrates the response when a requested resource is not found. It contains a specific error code and a descriptive message.

```json
{
  "error": {
    "code": "resource_not_found",
    "message": "The requested resource was not found"
  }
}
```

--------------------------------

### Add a Domain

Source: https://docs.gorillaa.one/guides/domains

Add a new domain to your account. This initiates the process of domain verification and authentication.

```APIDOC
## POST /v1/domains

### Description
Adds a new domain to your account for sending emails. After adding, you will receive DNS records to configure at your DNS provider.

### Method
POST

### Endpoint
/v1/domains

### Parameters
#### Request Body
- **domain** (string) - Required - The domain name you want to add (e.g., "yourdomain.com").

### Request Example
```json
{
  "domain": "yourdomain.com"
}
```

### Response
#### Success Response (200)
- **data** (object) - Contains the details of the added domain.
  - **id** (string) - The unique identifier for the domain.
  - **domain** (string) - The domain name that was added.
  - **subdomain** (string|null) - The subdomain associated with the domain, if any.
  - **verification_status** (string) - The current verification status (e.g., "pending").
  - **verified_at** (string|null) - The timestamp when the domain was verified.
  - **dkim_selector** (string) - The DKIM selector provided by the service.
  - **dkim_status** (string|null) - The DKIM verification status.
  - **warming_status** (string) - The status of the domain warming process.
  - **warming_current_limit** (string|null) - The current sending limit during warming.
  - **reputation_score** (string|null) - The reputation score of the domain.
  - **is_default** (boolean) - Indicates if this is the default sending domain.
  - **records** (array) - An array of DNS records required for verification and authentication.
    - **type** (string) - The type of DNS record (e.g., "TXT", "CNAME").
    - **host** (string) - The host or name for the DNS record.
    - **value** (string) - The value of the DNS record.
    - **priority** (string|null) - The priority for the DNS record (if applicable).
    - **purpose** (string) - The purpose of the DNS record (e.g., "verification", "dkim", "spf", "dmarc").
    - **verified** (boolean) - Indicates if the DNS record has been verified.
  - **created_at** (string) - The timestamp when the domain was created.
  - **updated_at** (string) - The timestamp when the domain was last updated.

#### Response Example
```json
{
  "data": {
    "id": "dom_abc123",
    "domain": "yourdomain.com",
    "subdomain": null,
    "verification_status": "pending",
    "verified_at": null,
    "dkim_selector": "gorillaa",
    "dkim_status": null,
    "warming_status": "not_started",
    "warming_current_limit": null,
    "reputation_score": null,
    "is_default": false,
    "records": [
      {
        "type": "TXT",
        "host": "_gorillaa-verify.yourdomain.com",
        "value": "gorillaa-verify=a1b2c3d4e5f6...",
        "priority": null,
        "purpose": "verification",
        "verified": false
      },
      {
        "type": "CNAME",
        "host": "gorillaa._domainkey.yourdomain.com",
        "value": "gorillaa._domainkey.yourdomain.com.mail.gorillaa.one",
        "priority": null,
        "purpose": "dkim",
        "verified": false
      },
      {
        "type": "TXT",
        "host": "yourdomain.com",
        "value": "v=spf1 include:_spf.mail.gorillaa.one ~all",
        "priority": null,
        "purpose": "spf",
        "verified": false
      },
      {
        "type": "TXT",
        "host": "_dmarc.yourdomain.com",
        "value": "v=DMARC1; p=none; rua=mailto:dmarc@yourdomain.com",
        "priority": null,
        "purpose": "dmarc",
        "verified": false
      }
    ],
    "created_at": "2026-02-09T12:00:00Z",
    "updated_at": "2026-02-09T12:00:00Z"
  }
}
```
```

--------------------------------

### Example cURL Request for Sending Email

Source: https://docs.gorillaa.one/guides/authentication

This example demonstrates how to send an email using the Gorillaa Mail API via a cURL command. It includes the necessary headers for authorization and content type, along with a JSON payload specifying sender, recipient, subject, and HTML content.

```bash
curl -X POST https://api.mail.gorillaa.one/v1/emails \
  -H "Authorization: Bearer grl_live_0GyUBWMr1aFAkZdIh1l4n..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "you@yourdomain.com",
    "to": [{ "email": "user@example.com" }],
    "subject": "Test",
    "html": "<p>Hello!</p>"
  }'
```

--------------------------------

### Send Email

Source: https://docs.gorillaa.one/quickstart

Send your first email using the Gorillaa Mail API. This endpoint allows you to send transactional emails to your recipients.

```APIDOC
## POST /v1/emails

### Description
Send an email using the Gorillaa Mail API.

### Method
POST

### Endpoint
https://api.mail.gorillaa.one/v1/emails

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token for authentication.
- **Content-Type** (string) - Required - application/json

#### Request Body
- **from** (string) - Required - The sender's email address.
- **to** (array) - Required - An array of recipient objects, each with an 'email' field.
- **subject** (string) - Required - The subject line of the email.
- **html** (string) - Required - The HTML content of the email.

### Request Example
```json
{
  "from": "you@yourdomain.com",
  "to": [{ "email": "recipient@example.com" }],
  "subject": "Hello from Gorillaa!",
  "html": "<h1>It works!</h1>"
}
```

### Response
#### Success Response (202)
- **data** (object) - Contains details about the sent email.
  - **id** (string) - The unique identifier for the email.
  - **status** (string) - The current status of the email (e.g., 'queued').

#### Response Example
```json
{
  "data": {
    "id": "em_abc123",
    "status": "queued"
  }
}
```
```

--------------------------------

### Add Domain

Source: https://docs.gorillaa.one/quickstart

Add a new domain to your Gorillaa Mail account for sending emails. This is recommended for improved deliverability.

```APIDOC
## POST /v1/domains

### Description
Add a domain to your account for email sending.

### Method
POST

### Endpoint
https://api.mail.gorillaa.one/v1/domains

### Parameters
#### Headers
- **Authorization** (string) - Required - Bearer token for authentication.
- **Content-Type** (string) - Required - application/json

#### Request Body
- **domain** (string) - Required - The domain name to add.

### Request Example
```json
{
  "domain": "yourdomain.com"
}
```

### Response
#### Success Response (200)
- **data** (object) - Contains information about the added domain and required DNS records.
  - **domain** (string) - The verified domain name.
  - **dns_records** (array) - An array of DNS records that need to be configured.

#### Response Example
```json
{
  "data": {
    "domain": "yourdomain.com",
    "dns_records": [
      { "type": "TXT", "name": "_dmarc", "value": "V=DMARC1; p=none;" },
      { "type": "CNAME", "name": "selector1._domainkey", "value": "selector1.dkim.yourdomain.com" }
    ]
  }
}
```
```

--------------------------------

### Verify a Domain

Source: https://docs.gorillaa.one/guides/domains

Triggers the verification process for a previously added domain after its DNS records have been configured.

```APIDOC
## POST /v1/domains/:id/verify

### Description
Initiates the verification process for a domain. This should be called after you have configured the necessary DNS records at your DNS provider.

### Method
POST

### Endpoint
/v1/domains/:id/verify

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the domain to verify (e.g., "dom_abc123").

### Request Example
```bash
curl -X POST https://api.mail.gorillaa.one/v1/domains/dom_abc123/verify \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response
#### Success Response (200)
- The response typically indicates success or provides updated domain status. Specific fields may vary, but often include the domain's updated verification status.

#### Response Example
(Example response structure may vary, check API documentation for specifics)
```json
{
  "message": "Verification process initiated successfully.",
  "data": {
    "id": "dom_abc123",
    "domain": "yourdomain.com",
    "verification_status": "pending_verification",
    "verified_at": null
    // ... other domain details
  }
}
```
```

--------------------------------

### Rate Limited Error Response Example

Source: https://docs.gorillaa.one/api-reference/domains/trigger-dns-verification

This example demonstrates the JSON response when API rate limits or quotas are exceeded. It includes an error code, message, and information about when to retry.

```json
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 60 seconds."
  }
}
```

--------------------------------

### Unauthorized Error Response Example

Source: https://docs.gorillaa.one/api-reference/domains/trigger-dns-verification

This example shows the JSON structure for an unauthorized error, typically due to an invalid or missing API key. It includes a code, message, and a suggestion for correction.

```json
{
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid API key provided",
    "suggestion": "Include a valid API key in the Authorization header: Bearer grl_live_..."
  }
}
```

--------------------------------

### List and Delete Domains

Source: https://docs.gorillaa.one/guides/domains

Endpoints for listing all domains associated with an organization and for deleting a specific domain.

```APIDOC
## List and Delete Domains

### List all domains

#### Description
Retrieves a list of all domains associated with your organization.

#### Method
GET

#### Endpoint
`/v1/domains`

#### Response
##### Success Response (200)
- **data** (array) - An array of domain objects.
- **total** (integer) - The total number of domains.

##### Response Example
```json
{
  "data": [ /* array of domain objects */ ],
  "total": 3
}
```

### Delete a domain

#### Description
Deletes a specific domain and all its associated configurations.

#### Method
DELETE

#### Endpoint
`/v1/domains/:id`

#### Parameters
##### Path Parameters
- **id** (string) - Required - The ID of the domain to delete.

#### Response
##### Success Response (200)
- **success** (boolean) - Indicates if the deletion was successful.

##### Response Example
```json
{
  "success": true
}
```

<Warning>
  Deleting a domain removes all associated DNS configurations. Emails already queued for this domain will still attempt delivery.
</Warning>
```

--------------------------------

### POST /v1/domains/:id/set-default

Source: https://docs.gorillaa.one/guides/domains

Sets a specified domain as the default sender for the organization.

```APIDOC
## POST /v1/domains/:id/set-default

### Description
Sets the specified domain as the default sender domain for your organization.

### Method
POST

### Endpoint
`/v1/domains/:id/set-default`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the domain to set as default.

### Request Example
```bash
curl -X POST https://api.mail.gorillaa.one/v1/domains/dom_abc123/set-default \
  -H "Authorization: Bearer YOUR_API_KEY"
```
```

--------------------------------

### Send First Email using Node.js

Source: https://docs.gorillaa.one/quickstart

This snippet shows how to send an email using the Gorillaa Mail API with Node.js and the Fetch API. It requires an API key and includes sender, recipient, subject, and HTML content in the request body.

```javascript
const response = await fetch("https://api.mail.gorillaa.one/v1/emails", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    from: "you@yourdomain.com",
    to: [{ email: "recipient@example.com" }],
    subject: "Hello from Gorillaa!",
    html: "<h1>It works!</h1>",
  }),
});

const data = await response.json();
console.log(data);
// { data: { id: "em_abc123", status: "queued" } }
```

--------------------------------

### Send First Email using cURL

Source: https://docs.gorillaa.one/quickstart

This snippet demonstrates how to send your first email using the Gorillaa Mail API via cURL. It requires an API key and specifies sender, recipient, subject, and HTML content.

```bash
curl -X POST https://api.mail.gorillaa.one/v1/emails \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ \
    "from": "you@yourdomain.com", \
    "to": [{ "email": "recipient@example.com" }], \
    "subject": "Hello from Gorillaa!", \
    "html": "<h1>It works!</h1>" \
   }'
```

--------------------------------

### Send First Email using Python

Source: https://docs.gorillaa.one/quickstart

This snippet demonstrates sending an email via the Gorillaa Mail API using Python's requests library. It requires an API key and sends sender, recipient, subject, and HTML content in a JSON payload.

```python
import requests

response = requests.post(
    "https://api.mail.gorillaa.one/v1/emails",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "from": "you@yourdomain.com",
        "to": [{"email": "recipient@example.com"}],
        "subject": "Hello from Gorillaa!",
        "html": "<h1>It works!</h1>",
    },
)

print(response.json())
# {"data": {"id": "em_abc123", "status": "queued"}}
```

--------------------------------

### Send Email with net/smtp (Go)

Source: https://docs.gorillaa.one/guides/smtp

This Go snippet shows how to send an email using the standard 'net/smtp' package. It sets up the authentication, formats the email message as a byte slice, and uses 'smtp.SendMail' to transmit it.

```go
package main

import (
    "net/smtp"
    "os"
)

func main() {
    auth := smtp.PlainAuth("", "gorillaa", os.Getenv("GORILLAA_API_KEY"), "smtp.gorillaa.one")

    msg := []byte("From: you@yourdomain.com\r\n" +
        "To: recipient@example.com\r\n" +
        "Subject: Hello from Gorillaa!\r\n" +
        "Content-Type: text/html\r\n\r\n" +
        "<h1>It works!</h1>\r\n")

    smtp.SendMail("smtp.gorillaa.one:587", auth, "you@yourdomain.com",
        []string{"recipient@example.com"}, msg)
}
```

--------------------------------

### BadRequest Error Example

Source: https://docs.gorillaa.one/api-reference/gdpr/gdpr-data-export-async

An example of a BadRequest response, indicating invalid request parameters or body. It shows a validation failure for a required 'subject' field.

```json
{
  "error": {
    "code": "invalid_request",
    "message": "Request validation failed",
    "details": {
      "validation": {
        "subject": [
          "Subject is required"
        ]
      }
    },
    "suggestion": "Check the request body against the API documentation"
  }
}
```

--------------------------------

### Get Detailed Health Information (YAML)

Source: https://docs.gorillaa.one/api-reference/health/detailed-health-with-memory-and-uptime

This OpenAPI specification defines the GET /health/detailed endpoint, which retrieves detailed health information about the service, including status, timestamp, uptime, memory usage, and environment details. It's useful for monitoring service health and performance.

```yaml
openapi: 3.1.0
info:
  title: Gorillaa Mail API
  version: 1.0.0
  description: >
    Gorillaa Mail is a transactional email API service. Send emails, manage
    domains,

    track delivery analytics, handle suppressions, and comply with GDPR/privacy
    regulations.


    ## Authentication

    All `/v1/*` endpoints require a Bearer API key in the `Authorization`
    header:

    ```

    Authorization: Bearer grl_live_xxxxxxxxxxxx

    ```

    API keys are scoped — each key is granted specific permissions (e.g. 
    `email:send`, `domain:read`).


    ## Test Mode

    API keys prefixed with `grl_test_` operate in test mode with reduced limits.

    Test mode responses include `X-Gorillaa-Test-Mode: true` header.


    ## Rate Limiting

    All authenticated endpoints return rate limit headers:

    - `X-RateLimit-Limit` — max requests in window

    - `X-RateLimit-Remaining` — remaining requests

    - `X-RateLimit-Reset` — UTC epoch when window resets


    ## Idempotency

    The `POST /v1/emails` endpoint supports idempotency via the
    `X-Idempotency-Key` header.

    Repeat requests with the same key within 24 hours return the original
    response.


    ## Pagination

    List endpoints use page-based pagination (`page` + `limit`) or offset-based
    (`offset` + `limit`).
  contact:
    name: Gorillaa Mail Support
    url: https://gorillaa.one
    email: support@gorillaa.one
  license:
    name: Proprietary
    url: https://gorillaa.one/terms
servers:
  - url: https://api.mail.gorillaa.one
    description: Production
  - url: http://localhost:8787
    description: Local development
security:
  - BearerApiKey: []
tags:
  - name: Emails
    description: Send, list, and inspect transactional emails
  - name: Domains
    description: Register, verify, and manage sender domains
  - name: Statistics
    description: Delivery analytics, domain breakdown, and reputation metrics
  - name: Suppressions
    description: Manage suppressed/bounced email addresses
  - name: Privacy
    description: GDPR-compliant data export, erasure, and privacy preferences
  - name: GDPR
    description: Data Subject Request operations (Art. 15 export, Art. 17 erasure)
  - name: Health
    description: Service health and readiness probes
paths:
  /health/detailed:
    get:
      tags:
        - Health
      summary: Detailed health with memory and uptime
      operationId: detailedHealth
      responses:
        '200':
          description: Detailed health information
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  timestamp:
                    type: string
                    format: date-time
                  uptime:
                    type: number
                    description: Uptime in seconds
                  memory:
                    type: object
                    properties:
                      rss:
                        type: number
                      heapUsed:
                        type: number
                      heapTotal:
                        type: number
                  services: 7b033136-5453-4ba5-812d-33071d922a1d
                  environment:
                    type: object
                    properties:
                      nodeVersion:
                        type: string
                      platform:
                        type: string
                      arch:
                        type: string
                required:
                  - status
                  - timestamp
                  - uptime
      security: []
components:
  securitySchemes:
    BearerApiKey:
      type: http
      scheme: bearer
      description: >
        API key authentication. Pass your Gorillaa Mail API key as a Bearer
        token.


        Example: `Authorization: Bearer grl_live_xxxxxxxxxxxx`


        Keys prefixed `grl_test_` operate in test mode with reduced limits.

```

--------------------------------

### Add Domain using cURL

Source: https://docs.gorillaa.one/quickstart

This cURL command demonstrates how to add a domain to your Gorillaa Mail account for improved deliverability. It requires your API key and the domain name.

```bash
# Add a domain
curl -X POST https://api.mail.gorillaa.one/v1/domains \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "domain": "yourdomain.com" }'
```

--------------------------------

### OpenAPI Specification for GET /v1/stats/domains

Source: https://docs.gorillaa.one/api-reference/statistics/get-per-domain-statistics

This OpenAPI 3.1.0 specification defines the GET /v1/stats/domains endpoint for retrieving per-domain statistics. It includes request parameters for date ranges and optional domain filtering, as well as response schemas for successful and error cases. Requires the 'stats:read' scope for access.

```yaml
openapi: 3.1.0
info:
  title: Gorillaa Mail API
  version: 1.0.0
  description: >
    Gorillaa Mail is a transactional email API service. Send emails, manage
    domains,

    track delivery analytics, handle suppressions, and comply with GDPR/privacy
    regulations.


    ## Authentication

    All `/v1/*` endpoints require a Bearer API key in the `Authorization`
    header:

    ```

    Authorization: Bearer grl_live_xxxxxxxxxxxx

    ```

    API keys are scoped — each key is granted specific permissions (e.g. 
    `email:send`, `domain:read`).


    ## Test Mode

    API keys prefixed with `grl_test_` operate in test mode with reduced limits.

    Test mode responses include `X-Gorillaa-Test-Mode: true` header.


    ## Rate Limiting

    All authenticated endpoints return rate limit headers:

    - `X-RateLimit-Limit` — max requests in window

    - `X-RateLimit-Remaining` — remaining requests

    - `X-RateLimit-Reset` — UTC epoch when window resets


    ## Idempotency

    The `POST /v1/emails` endpoint supports idempotency via the
    `X-Idempotency-Key` header.

    Repeat requests with the same key within 24 hours return the original
    response.


    ## Pagination

    List endpoints use page-based pagination (`page` + `limit`) or offset-based
    (`offset` + `limit`).
  contact:
    name: Gorillaa Mail Support
    url: https://gorillaa.one
    email: support@gorillaa.one
  license:
    name: Proprietary
    url: https://gorillaa.one/terms
servers:
  - url: https://api.mail.gorillaa.one
    description: Production
  - url: http://localhost:8787
    description: Local development
security:
  - BearerApiKey: []
tags:
  - name: Emails
    description: Send, list, and inspect transactional emails
  - name: Domains
    description: Register, verify, and manage sender domains
  - name: Statistics
    description: Delivery analytics, domain breakdown, and reputation metrics
  - name: Suppressions
    description: Manage suppressed/bounced email addresses
  - name: Privacy
    description: GDPR-compliant data export, erasure, and privacy preferences
  - name: GDPR
    description: Data Subject Request operations (Art. 15 export, Art. 17 erasure)
  - name: Health
    description: Service health and readiness probes
paths:
  /v1/stats/domains:
    get:
      tags:
        - Statistics
      summary: Get per-domain statistics
      description: |
        Returns delivery metrics broken down by sending domain.

        Requires `stats:read` scope.
      operationId: getStatsByDomain
      parameters:
        - $ref: '#/components/parameters/StartDate'
        - $ref: '#/components/parameters/EndDate'
        - $ref: '#/components/parameters/OptionalDomainId'
      responses:
        '200':
          description: Per-domain statistics
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/DomainBreakdownResponse'
                required:
                  - data
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  parameters:
    StartDate:
      name: start_date
      in: query
      required: true
      description: Start of date range (ISO 8601 datetime)
      schema:
        type: string
        format: date-time
    EndDate:
      name: end_date
      in: query
      required: true
      description: End of date range (ISO 8601 datetime). Must be after start_date.
      schema:
        type: string
        format: date-time
    OptionalDomainId:
      name: domain_id
      in: query
      required: false
      description: Filter by specific domain UUID
      schema:
        type: string
        format: uuid
  schemas:
    DomainBreakdownResponse:
      type: object
      required:
        - period
        - domains
      properties:
        period:
          $ref: '#/components/schemas/DateRange'
        domains:
          type: array
          items:
            $ref: '#/components/schemas/DomainStats'
    DateRange:
      type: object
      required:
        - from
        - to
      properties:
        from:
          type: string
          format: date-time
        to:
          type: string
          format: date-time
    DomainStats:
      type: object
      required:
        - domain
        - total
        - delivered
        - bounced
        - failed
        - opens
        - clicks
        - deliveryRate
        - openRate
      properties:
        domain:
          type: string
        total:
          type: integer
        delivered:
          type: integer
        bounced:
          type: integer
        failed:
          type: integer
        opens:
          type: integer
        clicks:
          type: integer
        deliveryRate:
          type: number
          format: float

```

--------------------------------

### GET /v1/suppressions/check

Source: https://docs.gorillaa.one/api-reference/suppressions/check-if-an-email-is-suppressed

Check if a specific email address is on the suppression list. Requires `suppression:read` scope.

```APIDOC
## GET /v1/suppressions/check

### Description
Check whether a specific email address is on the suppression list.

Requires `suppression:read` scope.

### Method
GET

### Endpoint
/v1/suppressions/check

### Parameters
#### Query Parameters
- **email** (string) - Required - The email address to check.

### Request Example
```
GET /v1/suppressions/check?email=test@example.com
```

### Response
#### Success Response (200)
- **data** (object) - The suppression check result.
  - **email** (string) - The email address checked.
  - **suppressed** (boolean) - Indicates if the email is suppressed.
  - **reason** (SuppressionReason) - The reason for suppression.

#### Response Example
```json
{
  "data": {
    "email": "test@example.com",
    "suppressed": true,
    "reason": "hard_bounce"
  }
}
```

#### Error Responses
- **400** - Bad Request
- **401** - Unauthorized
```

--------------------------------

### Verify Domain API Request (Bash)

Source: https://docs.gorillaa.one/guides/domains

This cURL command initiates the domain verification process after you have configured the necessary DNS records. You need to replace ':id' with the actual domain ID obtained from the 'Add Domain' API response and include your API key for authorization.

```bash
curl -X POST https://api.mail.gorillaa.one/v1/domains/dom_abc123/verify \
  -H "Authorization: Bearer YOUR_API_KEY"
```

--------------------------------

### Common Error Responses

Source: https://docs.gorillaa.one/api-reference/domains/set-as-default-domain

Describes common error responses, including Unauthorized and Not Found, with their respective structures and examples.

```APIDOC
## Common Error Responses

### Unauthorized

#### Description
Returned when the API key is missing, invalid, expired, or revoked.

#### Content
- **Content-Type**: `application/json`
- **Schema**: `#/components/schemas/ErrorResponse`

#### Example
```json
{
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid API key provided",
    "suggestion": "Include a valid API key in the Authorization header: Bearer grl_live_..."
  }
}
```

### Not Found

#### Description
Returned when the requested resource does not exist.

#### Content
- **Content-Type**: `application/json`
- **Schema**: `#/components/schemas/ErrorResponse`

#### Example
```json
{
  "error": {
    "code": "resource_not_found",
    "message": "The requested resource was not found"
  }
}
```
```

--------------------------------

### GET /v1/gdpr/status

Source: https://docs.gorillaa.one/guides/gdpr-privacy

View the history and status of all GDPR requests made.

```APIDOC
## GET /v1/gdpr/status

### Description
View the history and status of all GDPR requests.

### Method
GET

### Endpoint
/v1/gdpr/status

### Parameters
#### Query Parameters
None

### Request Example
```bash
curl "https://api.mail.gorillaa.one/v1/gdpr/status" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response
#### Success Response (200)
- **data** (array) - A list of GDPR request objects.
  - **id** (string) - Unique identifier for the request.
  - **type** (string) - Type of request (e.g., "export", "erasure").
  - **email** (string) - The email address associated with the request.
  - **requestedBy** (string) - Identifier for who made the request.
  - **status** (string) - Current status of the request (pending, processing, completed, failed, cancelled).
  - **createdAt** (string) - Timestamp when the request was created.
  - **completedAt** (string) - Timestamp when the request was completed (if applicable).

#### Response Example
```json
{
  "data": [
    {
      "id": "dsr_abc123",
      "type": "export",
      "email": "user@example.com",
      "requestedBy": "api_key_xyz",
      "status": "completed",
      "createdAt": "2026-02-09T12:00:00Z",
      "completedAt": "2026-02-09T12:05:00Z"
    },
    {
      "id": "dsr_def456",
      "type": "erasure",
      "email": "user@example.com",
      "requestedBy": "api_key_xyz",
      "status": "processing",
      "createdAt": "2026-02-09T12:10:00Z"
    }
  ]
}
```

### Request statuses
| Status       | Description                          |
|--------------|--------------------------------------|
| `pending`    | Request received, not yet started    |
| `processing` | Request is being processed           |
| `completed`  | Request completed successfully       |
| `failed`     | Request failed (check error details) |
| `cancelled`  | Request was cancelled                |
```

--------------------------------

### Domain Warming Information

Source: https://docs.gorillaa.one/guides/domains

Provides details on the domain warming process, including the daily sending limits over time and the different warming statuses.

```APIDOC
## Domain Warming

### Description
This section outlines the domain warming process, which gradually increases daily sending capacity for new domains. It details the daily limits and the different warming statuses.

### Daily Limits
| Day | Daily limit |
| --- | ------------- |
| 1   | 20            |
| 2   | 40            |
| 3   | 80            |
| 4   | 160           |
| 5   | 320           |
| 6   | 640           |
| 7   | 1,280         |
| 14  | 2,560         |
| 21  | 5,120         |
| 28  | 10,000        |
| 35+ | **Unlimited** |

### Warming Status
- **not_started**: Domain verified but no emails sent yet.
- **warming**: Active warming — limits are gradually increasing.
- **warmed**: Domain is fully warmed, no volume restrictions.
- **paused**: Warming paused due to high bounce/complaint rate.

<Warning>
  If your bounce rate exceeds thresholds during warming, the process is automatically paused to protect your sender reputation. Investigate bounces before resuming.
</Warning>
```

--------------------------------

### GET /v1/privacy/preferences

Source: https://docs.gorillaa.one/api-reference/privacy/get-privacy-preferences

Retrieve the organization's privacy preference settings. This endpoint requires the `privacy:read` scope.

```APIDOC
## GET /v1/privacy/preferences

### Description
Retrieve the organization's privacy preference settings.

Requires `privacy:read` scope.

### Method
GET

### Endpoint
/v1/privacy/preferences

### Parameters
#### Query Parameters
- **page** (integer) - Optional - The page number for pagination.
- **limit** (integer) - Optional - The number of items per page.

### Request Example
```json
{
  "example": "No request body for GET request."
}
```

### Response
#### Success Response (200)
- **data** (object) - Contains the privacy preferences.
  - **doNotSell** (boolean) - Indicates if the organization has opted out of selling data.
  - **marketingEmails** (boolean) - Indicates if the organization opts in for marketing emails.
  - **productUpdates** (boolean) - Indicates if the organization opts in for product updates.
  - **updatedAt** (string, format: date-time) - The timestamp when the preferences were last updated.

#### Response Example
```json
{
  "data": {
    "doNotSell": true,
    "marketingEmails": false,
    "productUpdates": true,
    "updatedAt": "2023-10-27T10:00:00Z"
  }
}
```

#### Error Response (401)
- **error** (object) - Contains error details.
  - **code** (string) - The error code (e.g., `invalid_api_key`, `insufficient_permissions`).
  - **message** (string) - A human-readable error message.
  - **details** (object) - Additional structured error details.
  - **suggestion** (string) - An actionable suggestion to resolve the error.

#### Error Response Example
```json
{
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API key is invalid or expired.",
    "suggestion": "Please check your API key and ensure it is valid and active."
  }
}
```
```
Tokens:
Raw