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

# Quickstart

> Get started with Simple Email API in under 2 minutes.

# Quickstart

This guide will get you sending emails in minutes using our TypeScript SDK or your preferred method.

<Steps>
  <Step title="Install the SDK">
    Install the package using your favorite package manager:

    <CodeGroup>
      ```bash npm theme={null}
      npm install simpleemailapi
      ```

      ```bash pnpm theme={null}
      pnpm add simpleemailapi
      ```

      ```bash yarn theme={null}
      yarn add simpleemailapi
      ```
    </CodeGroup>
  </Step>

  <Step title="Get your API Key">
    Sign up on the [dashboard](https://simpleemailapi.dev/dashboard), create a workspace, and grab your API key (starts with `sea_live_`).
  </Step>

  <Step title="Send your first email">
    Use one of the methods below to send your first email.

    <CodeGroup>
      ```typescript TypeScript theme={null}
      import { createClient } from 'simpleemailapi';

      const client = createClient({
        apiKey: 'sea_live_...'
      });

      await client.send({
        from: 'onboarding@yourdomain.com',
        to: ['you@example.com'],
        subject: 'Hello from Simple Email API',
        body: 'It works!'
      });
      ```

      ```go Go theme={null}
      package main

      import (
          "context"
          "log"

          emailapi "github.com/emailapi/sdk-go"
          v1 "github.com/emailapi/sdk-go/gen/v1"
      )

      func main() {
          client := emailapi.NewClient("sea_live_...")

          _, err := client.Send(context.Background(), &v1.SendEmailRequest{
              From:    "onboarding@yourdomain.com",
              To:      []string{"you@example.com"},
              Subject: "Hello from Simple Email API",
              Body:    "It works!",
          })
          if err != nil {
              log.Fatal(err)
          }
      }
      ```

      ```typescript Connect theme={null}
      import { createClient } from "@connectrpc/connect";
      import { createConnectTransport } from "@connectrpc/connect-node";
      import { EmailService } from "@buf/simpleemailapi_public.connectrpc_es/v1/email_connect";

      const transport = createConnectTransport({
        baseUrl: "https://api.simpleemailapi.dev",
        httpVersion: "2",
        interceptors: [
          (next) => async (req) => {
            req.header.set("Authorization", "Bearer sea_live_...");
            return next(req);
          },
        ],
      });

      const client = createClient(EmailService, transport);

      // Access the raw Connect RPC client
      await client.sendEmail({
        from: "onboarding@yourdomain.com",
        to: ["you@example.com"],
        subject: "Hello from Connect RPC",
        body: "Using the typed RPC client directly!",
      });
      ```

      ```bash cURL theme={null}
      curl -X POST https://api.simpleemailapi.dev/v1/v1.EmailService/SendEmail \
        -H "Authorization: Bearer sea_live_..." \
        -H "Content-Type: application/json" \
        -d '{
          "from": "onboarding@yourdomain.com",
          "to": ["you@example.com"],
          "subject": "Hello from cURL",
          "body": "It works!"
        }'
      ```

      ```bash buf curl theme={null}
      buf curl \
        --schema buf.build/simpleemailapi/public \
        --header "Authorization: Bearer sea_live_..." \
        --data '{
          "from": "onboarding@yourdomain.com",
          "to": ["you@example.com"],
          "subject": "Hello from buf curl",
          "body": "It works!"
        }' \
        https://api.simpleemailapi.dev/v1.EmailService/SendEmail
      ```
    </CodeGroup>
  </Step>

  <Step title="Receive Emails">
    Handle incoming emails and events using your preferred method.

    <CodeGroup>
      ```typescript SDK (onReceive) theme={null}
      import { createClient } from 'simpleemailapi';

      const client = createClient({ apiKey: 'sea_live_...' });

      // Listen for events in real-time
      client.onReceive({
        onDelivered: (event) => console.log('Delivered:', event),
        onReplied: (event) => console.log('Reply:', event.body),
        onBounced: (event) => console.log('Bounced:', event),
        onError: (err) => console.error(err)
      });
      ```

      ```go Go SDK (OnReceive) theme={null}
      ctx, cancel := context.WithCancel(context.Background())
      defer cancel()

      client.OnReceive(ctx, emailapi.EventHandlers{
          OnDelivered: func(e *v1.EmailDeliveredEvent) {
              log.Println("Delivered to:", e.Recipients)
          },
          OnReplied: func(e *v1.EmailRepliedEvent) {
              log.Println("Reply from:", e.From)
          },
          OnBounced: func(e *v1.EmailBouncedEvent) {
              log.Println("Bounced:", e.BounceType)
          },
          OnError: func(err error) {
              log.Println("Error:", err)
          },
      })
      ```

      ```typescript Connect (Stream) theme={null}
      import { createClient } from "@connectrpc/connect";
      import { createConnectTransport } from "@connectrpc/connect-node";
      import { EmailService } from "@buf/simpleemailapi_public.connectrpc_es/v1/email_connect";

      const transport = createConnectTransport({
        baseUrl: "https://api.simpleemailapi.dev",
        httpVersion: "2",
        interceptors: [
          (next) => async (req) => {
            req.header.set("Authorization", "Bearer sea_live_...");
            return next(req);
          },
        ],
      });

      const client = createClient(EmailService, transport);

      const stream = client.streamEvents({
        cursor: "0",
      });

      for await (const event of stream) {
        console.log("New Event:", event);
      }
      ```

      ```bash cURL (Stream) theme={null}
      # Use -N to disable buffering for streaming responses
      curl -N -X POST https://api.simpleemailapi.dev/v1/v1.EmailService/StreamEvents \
        -H "Authorization: Bearer sea_live_..." \
        -H "Content-Type: application/json" \
        -d '{ "cursor": "0" }'
      ```

      ```bash buf curl (Stream) theme={null}
      buf curl \
        --schema buf.build/simpleemailapi/public \
        --header "Authorization: Bearer sea_live_..." \
        --data '{ "cursor": "0" }' \
        https://api.simpleemailapi.dev/v1.EmailService/StreamEvents
      ```

      ```typescript Webhook theme={null}
      import express from 'express';
      import { Webhook } from 'svix';

      const app = express();

      app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
        const secret = process.env.WEBHOOK_SECRET;
        const headers = req.headers;
        const payload = req.body;

        const wh = new Webhook(secret);
        const event = wh.verify(payload, headers);

        console.log('Webhook received:', event);
        res.json({ received: true });
      });

      app.listen(3000);
      ```
    </CodeGroup>
  </Step>
</Steps>

## Next Steps

<CardGroup cols={2}>
  <Card title="Add your domain" icon="globe" href="/domains">
    Configure your own domain to send from your brand.
  </Card>

  <Card title="Receive emails" icon="inbox" href="/receiving/on-receive">
    Listen for replies and events in real-time.
  </Card>
</CardGroup>