> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryrelaybase.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Go

> Official Go SDK for the Relaybase API

Go client for the Relaybase email validation API.

<Card title="GitHub Repository" icon="github" href="https://github.com/Vusion-Labs/relaybase_golang_sdk">
  Source, issues, and releases for the Relaybase Go SDK.
</Card>

## Requirements

* Go 1.22+

## Installation

```bash theme={null}
go get github.com/Vusion-Labs/relaybase_golang_sdk
```

## Authentication

Get your API key from the [Relaybase dashboard](/getting-started/create-api-key) and pass it to `relaybase.New`:

```go theme={null}
client := relaybase.New("rb_key_...")
```

By default the client talks to `https://api.relaybase.com`. To point at a different environment:

```go theme={null}
client := relaybase.New("rb_key_...", relaybase.WithBaseURL("https://staging.api.relaybase.com"))
```

## Quick start

```go theme={null}
package main

import (
	"fmt"
	"log"

	"github.com/Vusion-Labs/relaybase_golang_sdk"
)

func main() {
	client := relaybase.New("rb_key_...")

	result, err := client.SingleVerify("jane@company.com", relaybase.EmailModeCheckFast)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(result.IsValid) // true
	fmt.Println(result.Status)  // "valid"
}
```

## Verifying an email

```go theme={null}
result, err := client.SingleVerify(email, relaybase.EmailModeCheckFast)
```

Or with a context (for timeouts/cancellation):

```go theme={null}
result, err := client.SingleVerifyContext(ctx, email, relaybase.EmailModeCheckFast)
```

If `mode` is left as the zero value (`""`), it defaults to `EmailModeCheckFast`.

### Verification modes

| Constant                         | Value      | Description                                           |
| -------------------------------- | ---------- | ----------------------------------------------------- |
| `relaybase.EmailModeCheckFast`   | `"fast"`   | Fast syntax/MX-level check                            |
| `relaybase.EmailModeCheckMedium` | `"medium"` | Adds deeper domain/mailbox checks                     |
| `relaybase.EmailModeCheckDeep`   | `"deep"`   | Most thorough check, including full SMTP verification |

See [Validation Results](/concepts/validation-results) for how these map to the API's `mode` field.

### Response fields

`SingleVerify` returns a `*relaybase.VerifyResult`:

| Field          | Type     | Description                                                            |
| -------------- | -------- | ---------------------------------------------------------------------- |
| `IsValid`      | `bool`   | Overall validity of the email                                          |
| `Status`       | `string` | e.g. `"valid"`, `"invalid"`, `"risky"`                                 |
| `Score`        | `int`    | Deliverability score (0–100)                                           |
| `Reason`       | `string` | Human-readable explanation of the result                               |
| `Suggestion`   | `string` | Suggested correction or note                                           |
| `SyntaxValid`  | `bool`   | Whether the address is syntactically valid                             |
| `MXValid`      | `bool`   | Whether the domain has valid MX records                                |
| `SMTPCode`     | `int`    | SMTP response code from mailbox verification                           |
| `CatchAll`     | `bool`   | Whether the domain accepts all addresses (catch-all)                   |
| `IsDisposable` | `bool`   | Whether the address is from a disposable email provider                |
| `IsFree`       | `bool`   | Whether the address is from a free email provider (Gmail, Yahoo, etc.) |
| `IsRoleBased`  | `bool`   | Whether the address is role-based (e.g. `support@`, `admin@`)          |

Example:

```go theme={null}
result, err := client.SingleVerify("jane@company.com", relaybase.EmailModeCheckFast)
if err != nil {
	log.Fatal(err)
}

if result.IsValid {
	fmt.Printf("%s is deliverable (score: %d)\n", "jane@company.com", result.Score)
} else {
	fmt.Printf("Invalid: %s\n", result.Reason)
}
```

## Error handling

Errors from the API are returned as `error`. To inspect the underlying HTTP status:

```go theme={null}
result, err := client.SingleVerify(email, relaybase.EmailModeCheckFast)
if err != nil {
	if apiErr, ok := relaybase.IsAPIError(err); ok {
		fmt.Println(apiErr.StatusCode) // e.g. 401
		fmt.Println(apiErr.Message)    // e.g. "invalid api key"
	}
	log.Fatal(err)
}
```

Common status codes:

| Code  | Meaning                                       |
| ----- | --------------------------------------------- |
| `400` | Malformed request (e.g. invalid email format) |
| `401` | Invalid or missing API key                    |
| `403` | Key valid but not authorized for this action  |
| `429` | Rate limit / quota exceeded                   |
| `500` | Internal server error                         |

## Roadmap

Bulk validation support for validating multiple emails in a single call is in progress and will be added in a future release.