From ed4a429a1d7e9579b8b975610c6cc98d32d246c5 Mon Sep 17 00:00:00 2001 From: Vincent Vu <172068404+rubixvi@users.noreply.github.com> Date: Tue, 17 Feb 2026 07:43:13 +1100 Subject: [PATCH] fix(doc): Correct API reference in Go package documentation (#354) * Correct API reference in Go package documentation Updated description to reference the useSend API instead of Unsend API. * Update documentation to reflect useSend branding Added a issue to the package maintainer. If maintainer isn't actively maintaining the package. Will fork it. * fix(docs): remove community section and update Go SDK documentation - Remove community section until content is ready. - Update Go SDK docs to useSend implementation. --- apps/docs/community-sdk/go.mdx | 106 ------------------------ apps/docs/docs.json | 5 +- apps/docs/get-started/go.mdx | 147 +++++++++++++++++++++++++++++++++ 3 files changed, 148 insertions(+), 110 deletions(-) delete mode 100644 apps/docs/community-sdk/go.mdx create mode 100644 apps/docs/get-started/go.mdx diff --git a/apps/docs/community-sdk/go.mdx b/apps/docs/community-sdk/go.mdx deleted file mode 100644 index f6df134..0000000 --- a/apps/docs/community-sdk/go.mdx +++ /dev/null @@ -1,106 +0,0 @@ ---- -title: Go -description: "The Unsend Go package lets you interact with the Unsend API to send and manage emails as well as domains. This is a quick guide on using the package to send emails and retrieve email information." -icon: golang ---- - - - This is a community-maintained package and not maintained by the Unsend. - - -**Shout out to [QGeeDev](https://bsky.app/profile/qgdev.co.uk) for maintaining this package.** - -## Installation - -To install the Unsend package, you can use go get: - -```bash -go get github.com/QGeeDev/unsend-go -``` - -## Related Links - -GitHub Repository: [GitHub](https://github.com/QGeeDev/unsend-go) - -## Usage - -Below is an example of how to use the Unsend package to send an email and retrieve email information. - -### Environment Variables - -```bash -export UNSEND_API_KEY="your-api-key" -export UNSEND_API_URL="https://app.unsend.dev" # or your self-hosted URL -``` - -### Initialize - -```go -client, err := unsend.NewClient() -``` - -### Sending Emails - -To send an email you will need to define the payload. After definition, you can use the `.SendEmail` method to send emails with the payload as a parameter. - -```go -func main() { - godotenv.Load() - - client, err := unsend.NewClient() - - if err != nil { - fmt.Printf("[ERROR] - %s\n", err.Error()) - os.Exit(1) - } - - request := &unsend.SendEmailRequest{ - To: []string{"youremail@gmail.com"}, - From: "hello@yourdomain.com", - Subject: "Unsend test email", - Text: "hello,\n\nUnsend is the best open source sending platform", - Html: "

hello,

Unsend is the best open source sending platform

check out unsend.dev

", - } - - response, err := client.Emails.SendEmail(context.Background(), *request) - - if err != nil { - fmt.Printf("[ERROR] - %s\n", err.Error()) - os.Exit(1) - } - - fmt.Printf("[SUCCESS] - %s\n", response.EmailId) -} - -``` - -### Retrieve Emails using the id - -The email will be retrieved using the ID you get after sending the mail. - -```go -func main() { - godotenv.Load() - - client, err := unsend.NewClient() - - getEmailRequest := unsend.GetEmailRequest{ - EmailId: "your-email-id", - } - - email, err := client.Emails.GetEmail(context.Background(), getEmailRequest) - - if err != nil { - fmt.Printf("[ERROR] - %s\n", err.Error()) - os.Exit(1) - } - - fmt.Printf("[SUCCESS] - %s\n", email.Id) -} -``` - -### More - -Checkout more examples in the [GitHub Repository](https://github.com/QGeeDev/unsend-go/tree/main/examples). - -It handles `emails`, `domains` & `contacts` APIs. diff --git a/apps/docs/docs.json b/apps/docs/docs.json index bb54345..0f15ef7 100644 --- a/apps/docs/docs.json +++ b/apps/docs/docs.json @@ -28,6 +28,7 @@ "introduction", "get-started/nodejs", "get-started/python", + "get-started/go", "get-started/local", "get-started/smtp" ] @@ -39,10 +40,6 @@ { "group": "Guides", "pages": ["guides/webhooks", "guides/use-with-react-email"] - }, - { - "group": "Community SDKs", - "pages": ["community-sdk/python", "community-sdk/go"] } ] }, diff --git a/apps/docs/get-started/go.mdx b/apps/docs/get-started/go.mdx new file mode 100644 index 0000000..f9ab8fb --- /dev/null +++ b/apps/docs/get-started/go.mdx @@ -0,0 +1,147 @@ +--- +title: Go +description: "The useSend Go package lets you interact with the useSend API to send emails, manage contacts, and work with domains. This guide covers basic setup and usage." +icon: golang +--- + +## Prerequisites + +- [useSend API key](https://app.usesend.com/dev-settings/api-keys) +- [Verified domain](https://app.usesend.com/domains) + +## Installation + +Install the useSend Go SDK: +```bash +go get github.com/usesend/usesend-go +``` + +## Initialize + +Create a new client using your API key. +```go +package main + +import ( + "context" + "log" + + usesend "github.com/usesend/usesend-go" +) + +func main() { + client, err := usesend.NewClient("us_12345") + if err != nil { + log.Fatal(err) + } +} +``` + +API keys can also be supplied via the `USESEND_API_KEY` environment variable. + +### Self-Hosted Setup + +If you are running a self-hosted version of useSend, provide the base URL using `WithBaseURL`. +```go +client, err := usesend.NewClient( + "us_12345", + usesend.WithBaseURL("https://app.usesend.com"), +) +if err != nil { + log.Fatal(err) +} +``` + + +The base URL should be the root domain only. Do not include `/api/v1`, as the SDK manages API paths internally. + + +### Options + +- `WithBaseURL(url string)`: Override the base API URL (e.g. for self-hosting) +- `WithHTTPClient(*http.Client)`: Provide a custom HTTP client + + +The default HTTP client uses a 30s timeout. Requests include a `User-Agent: usesend-go` header. + + +## Sending Emails +```go +resp, errResp, err := client.Emails.Send( + context.Background(), + usesend.SendEmailPayload{ + To: []string{"hello@acme.com"}, + From: "hello@company.com", + Subject: "useSend email", + HTML: "

useSend is the best open source product to send emails

", + Text: "useSend is the best open source product to send emails", + Headers: map[string]string{ + "X-Campaign": "welcome", + }, + }, +) + +if err != nil { + log.Fatal(err) +} + +if errResp != nil { + log.Fatalf("API error: %s", errResp.Message) +} + +log.Printf("Email queued with ID: %s", resp.EmailID) +``` + + +Custom headers are forwarded as-is. useSend only manages the `X-Usesend-Email-ID` and `References` headers. + + +## Managing Contacts + +### Get Contact Book ID + +Retrieve the contact book ID from the useSend dashboard. + +### Create Contacts +```go +contact, apiErr, err := client.Contacts.Create( + context.Background(), + "contactBook_123", + usesend.CreateContactPayload{ + Email: "hey@koushik.dev", + FirstName: "Koushik", + LastName: "KM", + }, +) + +if err != nil { + log.Fatal(err) // transport error +} + +if apiErr != nil { + log.Fatalf("API error: %s", apiErr.Message) +} + +log.Printf("Contact ID: %s", contact.ContactID) +``` + +### Update Contacts +```go +contact, apiErr, err := client.Contacts.Update( + context.Background(), + "contactBook_123", + "contact_456", + usesend.UpdateContactPayload{ + FirstName: "Koushik", + LastName: "KM", + }, +) + +if err != nil { + log.Fatal(err) +} + +if apiErr != nil { + log.Fatalf("API error: %s", apiErr.Message) +} +```