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

> ## Agent Instructions
> AhaSend stores all message data in the EU. See /facts.
> The API base URL is https://api.ahasend.com. Send the API key in the Authorization: Bearer header. See /api-reference/authentication.
> Use send.ahasend.com for SMTP. Ports 25, 587 and 2525 use STARTTLS. Port 465 is not supported. See /smtp.
> For send-only integrations, create an API Key v2 under Credentials → Add and scope it to messages:send:{your-domain}. See /send-api/credentials and /api-reference/scopes.

# Quickstart: Send Your First Email

> Send your first email with AhaSend: verify a domain, create an API key or SMTP credential, then send with cURL, Node.js, Python, PHP or Go.

Send your first email with AhaSend by verifying a domain, creating a credential, and calling the REST API or connecting to the SMTP relay.

> [!NOTE]
>
> **Before you start:** You'll need an AhaSend account. [Sign up for free](https://dash.ahasend.com/user/register) to get 1,000 emails per month at no cost.

**1. Sign Up & Verify Email**

1. **[Sign up for a free account](https://dash.ahasend.com/user/register)**
2. **Verify your email address** by clicking the link in your inbox
3. **Log in to your dashboard** to continue setup

**2. Add & Configure Domain**

Before you can send emails, you need to add and verify your domain:

1. **Add your domain** in your dashboard under [Domains](https://dash.ahasend.com/account/-/settings/domains)
2. **Add the DNS records** provided by AhaSend to your domain's DNS settings
3. **Wait for verification** (usually takes a few minutes)

> [!NOTE]
>
> **Need help with domain setup?** Check out our detailed [domain configuration guide](https://ahasend.com/docs/domains.md) for the required DNS records and links to DNS provider help.

> [!WARNING]
>
> **Important:** You cannot send emails until your domain is verified. The verification process ensures good deliverability and prevents spoofing.

**3. Choose Sending Method**

Decide how you want to send emails:

> [card] [HTTP API](#http-api)
>
> **Recommended for most applications**
>
> * Faster and more reliable
> * Better error handling
> * Rich metadata support

> [card] [SMTP Relay](#smtp-relay)
>
> **Use with existing email libraries**
>
> * Works with any SMTP-compatible library
> * Easy migration from other providers
> * Supports all programming languages

**4. Create Sending Credentials**

Create the appropriate credentials for your chosen method:

**For HTTP API:**

* Go to **Credentials → Add** in your dashboard and choose **API Key v2** for a send-only key (or use a full API v2 key with a send scope from **Account Settings → API Keys**)
* Click "Create API Key"
* Copy and securely store your API key

**For SMTP:**

* Go to **SMTP Credentials** in your dashboard
* Click "Create SMTP Credential"
* Save the username and password

> [!WARNING]
>
> Keep your credentials secure! Never commit them to version control or expose them in client-side code.

**5. Send & Verify First Email**

Send your first email using the code examples below, then verify delivery:

**After sending:**

1. **Check your inbox** - Your test email should arrive within seconds
2. **Check the Messages page** in your dashboard to see delivery status
3. **Look for a 202 response** with a message ID

> [!TIP]
>
> **Success!** See your email in both your inbox and the Messages page? You're all set up! 🎉

Jump to: [HTTP API](#http-api) | [SMTP Relay](#smtp-relay)

***

## Official SDKs

> [card] [Node.js and TypeScript SDK](https://ahasend.com/docs/guides/nodejs-sdk.md)
>
> Install @ahasend/sdk, send a sandbox email and handle each recipient result.

> [card] [Go SDK](https://ahasend.com/docs/guides/go-sdk.md)
>
> Install ahasend-go, send a sandbox email and verify webhook signatures.

Choose a [framework or platform guide](https://ahasend.com/docs/guides.md) for the full integration, or use the [CLI quickstart](https://ahasend.com/docs/cli/quickstart.md) to send from your terminal.

## How Do I Send Through the HTTP API?

Call `POST https://api.ahasend.com/v2/accounts/{account_id}/messages` with your API key and a sender on your verified domain. See [API authentication](https://ahasend.com/docs/api-reference/authentication.md) for the header and [sending limits](https://ahasend.com/docs/send-api/send-email.md#limits) before adding recipients.

> [!NOTE]
>
> **API Version Note:** These examples use our latest API v2, which provides the most powerful features including advanced tracking, bulk sending, and better error handling. Existing v1 integrations can use the [legacy API v1 reference](https://ahasend.com/docs/api-reference/v1.md); use v2 for new integrations.

### Basic Email

```bash cURL theme={null}
curl -X POST https://api.ahasend.com/v2/accounts/{account_id}/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "from": {
      "name": "My App",
      "email": "hello@yourdomain.com"
    },
    "recipients": [
      {
        "name": "John Doe",
        "email": "john@example.com"
      }
    ],
    "subject": "Welcome to My App!",
    "text_content": "Thanks for signing up. We'\''re excited to have you!",
    "html_content": "<h1>Welcome!</h1><p>Thanks for signing up. We'\''re <strong>excited</strong> to have you!</p>"
  }'
```

```javascript Node.js theme={null}
const axios = require('axios');

const sendEmail = async () => {
  try {
    const email = {
      from: {
        name: 'My App',
        email: 'hello@yourdomain.com'
      },
      recipients: [
        {
          name: 'John Doe',
          email: 'john@example.com'
        }
      ],
      subject: 'Welcome to My App!',
      text_content: 'Thanks for signing up. We\'re excited to have you!',
      html_content: '<h1>Welcome!</h1><p>Thanks for signing up. We\'re <strong>excited</strong> to have you!</p>'
    };

    const response = await axios.post('https://api.ahasend.com/v2/accounts/{account_id}/messages', email, {
      headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    });

    console.log('Email sent:', response.data);
  } catch (error) {
    console.error('Error:', error.response.data);
  }
};

sendEmail();
```

```python Python theme={null}
import requests

def send_email():
    url = 'https://api.ahasend.com/v2/accounts/{account_id}/messages'
    headers = {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer YOUR_API_KEY'
    }
    email = {
        'from': {
            'name': 'My App',
            'email': 'hello@yourdomain.com'
        },
        'recipients': [
            {
                'name': 'John Doe',
                'email': 'john@example.com'
            }
        ],
        'subject': 'Welcome to My App!',
        'text_content': 'Thanks for signing up. We\'re excited to have you!',
        'html_content': '<h1>Welcome!</h1><p>Thanks for signing up. We\'re <strong>excited</strong> to have you!</p>'
    }

    response = requests.post(url, json=email, headers=headers)

    if response.status_code == 202:
        print('Email sent:', response.json())
    else:
        print('Error:', response.json())

send_email()
```

```php PHP theme={null}
<?php
$email = [
    'sandbox' => true,
    'from' => [
        'name' => 'My App',
        'email' => 'hello@yourdomain.com'
    ],
    'recipients' => [
        [
            'name' => 'John Doe',
            'email' => 'john@example.com'
        ]
    ],
    'subject' => 'Welcome to My App!',
    'text_content' => 'Thanks for signing up. We\'re excited to have you!',
    'html_content' => '<h1>Welcome!</h1><p>Thanks for signing up. We\'re <strong>excited</strong> to have you!</p>'
];

$options = [
    'http' => [
        'header' => "Content-type: application/json\r\nAuthorization: Bearer YOUR_API_KEY",
        'method' => 'POST',
        'content' => json_encode($email)
    ]
];

$context = stream_context_create($options);
$response = file_get_contents('https://api.ahasend.com/v2/accounts/{account_id}/messages', false, $context);

echo $response;
?>
```

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

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

type Email struct {
    From        Contact   `json:"from"`
    Recipients  []Contact `json:"recipients"`
    Subject     string    `json:"subject"`
    TextContent string    `json:"text_content"`
    HTMLContent string    `json:"html_content"`
}

type Contact struct {
    Name  string `json:"name"`
    Email string `json:"email"`
}

func main() {
    email := Email{
        From: Contact{
            Name:  "My App",
            Email: "hello@yourdomain.com",
        },
        Recipients: []Contact{
            {
                Name:  "John Doe",
                Email: "john@example.com",
            },
        },
        Subject:     "Welcome to My App!",
        TextContent: "Thanks for signing up. We're excited to have you!",
        HTMLContent: "<h1>Welcome!</h1><p>Thanks for signing up. We're <strong>excited</strong> to have you!</p>",
    }

    jsonData, _ := json.Marshal(email)

    req, _ := http.NewRequest("POST", "https://api.ahasend.com/v2/accounts/{account_id}/messages", bytes.NewBuffer(jsonData))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        fmt.Println("Error:", err)
        return
    }
    defer resp.Body.Close()

    fmt.Println("Response Status:", resp.Status)
}
```

> [!TIP]
>
> **Replace the placeholders:**
>
> * `YOUR_API_KEY` with your actual API key from Step 4
> * `{account_id}` with your account ID from your dashboard
> * `hello@yourdomain.com` with your verified domain from Step 2
> * `john@example.com` with the recipient's email address

***

## How Do I Send Through SMTP?

Use our SMTP servers with any email library. Great for existing applications or when you need SMTP compatibility.

### SMTP Settings

```text theme={null}
Host: send.ahasend.com
Ports: 25, 587, 2525 (STARTTLS) or 465 (implicit TLS)
Authentication: Required
Username: Your SMTP username (from dashboard)
Password: Your SMTP password (from dashboard)
```

> [!NOTE]
>
> **Get SMTP credentials:** You should have created these in Step 4. If not, go to your dashboard → Credentials → Create New Credential

### SMTP Examples

```javascript Node.js (Nodemailer) theme={null}
const nodemailer = require('nodemailer');

const transporter = nodemailer.createTransport({
  host: 'send.ahasend.com',
  port: 587,
  secure: false,
  auth: {
    user: 'YOUR_SMTP_USERNAME',
    pass: 'YOUR_SMTP_PASSWORD'
  }
});

const mailOptions = {
  from: '"My App" <hello@yourdomain.com>',
  to: 'john@example.com',
  subject: 'Welcome to My App!',
  text: 'Thanks for signing up. We\'re excited to have you!',
  html: '<h1>Welcome!</h1><p>Thanks for signing up. We\'re <strong>excited</strong> to have you!</p>'
};

transporter.sendMail(mailOptions, (error, info) => {
  if (error) {
    console.error('Error:', error);
  } else {
    console.log('Email sent:', info.response);
  }
});
```

```python Python (smtplib) theme={null}
import smtplib
from email.mime.text import MIMEText
from email.mime.multipart import MIMEMultipart

# Create message
msg = MIMEMultipart('alternative')
msg['Subject'] = 'Welcome to My App!'
msg['From'] = 'My App <hello@yourdomain.com>'
msg['To'] = 'john@example.com'

# Create text and HTML parts
text = "Thanks for signing up. We're excited to have you!"
html = "<h1>Welcome!</h1><p>Thanks for signing up. We're <strong>excited</strong> to have you!</p>"

msg.attach(MIMEText(text, 'plain'))
msg.attach(MIMEText(html, 'html'))

# Send email
try:
    server = smtplib.SMTP('send.ahasend.com', 587)
    server.starttls()
    server.login('YOUR_SMTP_USERNAME', 'YOUR_SMTP_PASSWORD')
    server.send_message(msg)
    server.quit()
    print('Email sent successfully!')
except Exception as e:
    print(f'Error: {e}')
```

```php PHP (PHPMailer) theme={null}
<?php
use PHPMailer\PHPMailer\PHPMailer;
use PHPMailer\PHPMailer\SMTP;

require 'vendor/autoload.php';

$mail = new PHPMailer(true);

try {
    // Server settings
    $mail->isSMTP();
    $mail->Host       = 'send.ahasend.com';
    $mail->SMTPAuth   = true;
    $mail->Username   = 'YOUR_SMTP_USERNAME';
    $mail->Password   = 'YOUR_SMTP_PASSWORD';
    $mail->SMTPSecure = PHPMailer::ENCRYPTION_STARTTLS;
    $mail->Port       = 587;

    // Recipients
    $mail->setFrom('hello@yourdomain.com', 'My App');
    $mail->addAddress('john@example.com', 'John Doe');

    // Content
    $mail->isHTML(true);
    $mail->Subject = 'Welcome to My App!';
    $mail->Body    = '<h1>Welcome!</h1><p>Thanks for signing up. We\'re <strong>excited</strong> to have you!</p>';
    $mail->AltBody = 'Thanks for signing up. We\'re excited to have you!';

    $mail->send();
    echo 'Email sent successfully!';
} catch (Exception $e) {
    echo "Error: {$mail->ErrorInfo}";
}
?>
```

```go Go (gomail) theme={null}
package main

import (
    "gopkg.in/gomail.v2"
    "log"
)

func main() {
    m := gomail.NewMessage()
    m.SetHeader("From", "hello@yourdomain.com")
    m.SetHeader("To", "john@example.com")
    m.SetHeader("Subject", "Welcome to My App!")
    m.SetBody("text/plain", "Thanks for signing up. We're excited to have you!")
    m.AddAlternative("text/html", "<h1>Welcome!</h1><p>Thanks for signing up. We're <strong>excited</strong> to have you!</p>")

    d := gomail.NewDialer("send.ahasend.com", 587, "YOUR_SMTP_USERNAME", "YOUR_SMTP_PASSWORD")

    if err := d.DialAndSend(m); err != nil {
        log.Fatal(err)
    }

    log.Println("Email sent successfully!")
}
```

***

## Next Steps

Now that you've sent your first email, here's what to do next:

> [card] [Set up Domains](https://ahasend.com/docs/domains.md)
>
> **Add and verify domains** for better deliverability and custom from addresses

> [card] [Send with SMTP](https://ahasend.com/docs/smtp.md)
>
> **Use SMTP credentials** to send emails through your existing email libraries

> [card] [Send with API](https://ahasend.com/docs/api-reference/messages/create-message.md)
>
> **Advanced API features** like templates, attachments, and bulk sending

> [card] [Sandbox SMTP](https://ahasend.com/docs/send-api/sandbox.md)
>
> **Test safely** with sandbox mode to avoid sending emails to real recipients

## Why Did My First Send Fail?

Having issues? Here are the most common problems:

> [accordion] 401 Unauthorized Error
>
> * Check that your API key is correct and properly formatted
> * Make sure you're using the `Authorization: Bearer` header format
> * Verify your API key has the correct scopes in your dashboard

> [accordion] Domain Still Not Verified
>
> * Most records verify within minutes. DNS changes can take up to 48 hours to propagate.
> * Double-check that you added all required DNS records exactly as shown
> * Use a DNS checker tool to verify your records are live
> * Contact support if verification fails after 48 hours

> [accordion] SMTP Authentication Failed
>
> * Double-check your SMTP username and password
> * Make sure you created SMTP credentials in your dashboard (not your login password)
> * Try port 2525 if 587 is blocked by your network

> [accordion] Email Not Delivered
>
> * Check your dashboard message logs for delivery status
> * Verify the recipient email address is correct
> * Check the recipient's spam folder
> * Make sure you're not hitting monthly allowance (the Free plan includes 1,000 emails/month); see [API rate limits](https://ahasend.com/docs/api-reference/rate-limits.md) for request limits

> [!NOTE]
>
> **Need more help?** Email our engineering team at [support@ahasend.com](mailto:support@ahasend.com) - we typically respond within a few hours!

## Domain, Delivery and Migration Guides

* [DNS provider guides](https://ahasend.com/docs/dns.md): record names and setup steps for Cloudflare, GoDaddy, Namecheap, Route 53, Hetzner, IONOS, STRATO, TransIP, OVHcloud, Squarespace and Vercel.
* [SPF, DKIM and DMARC](https://ahasend.com/docs/email-authentication.md): what each check proves and how domain alignment works.
* [Bounces and suppressions](https://ahasend.com/docs/bounces.md) and [SMTP error codes](https://ahasend.com/docs/smtp/errors.md): understand a failed send and choose the next step.
* [Deliverability best practices](https://ahasend.com/docs/deliverability.md): sender reputation, warm-up, sending subdomains, Gmail and Yahoo requirements, and one-click unsubscribe.
* Migrate from [SendGrid](https://ahasend.com/docs/migrations/sendgrid.md), [Mailgun](https://ahasend.com/docs/migrations/mailgun.md), [Postmark](https://ahasend.com/docs/migrations/postmark.md), [Resend](https://ahasend.com/docs/migrations/resend.md) or [Amazon SES](https://ahasend.com/docs/migrations/amazon-ses.md), including suppression imports.
* [Troubleshooting and FAQ](https://ahasend.com/docs/troubleshooting.md): domain checks, missing messages, port 465, permission errors and blocked recipients.
* [Email glossary](https://ahasend.com/docs/glossary.md) and [credential security](https://ahasend.com/docs/security.md): definitions and practical steps to protect your account.

## Related Guides

* [Domain setup](https://ahasend.com/docs/domains.md), [Send-only API keys](https://ahasend.com/docs/send-api/credentials.md), [Sending guide](https://ahasend.com/docs/send-api/send-email.md).
* [SMTP settings](https://ahasend.com/docs/smtp.md), [CLI quickstart](https://ahasend.com/docs/cli/quickstart.md), [SDK and framework guides](https://ahasend.com/docs/guides.md).
* [Plans and limits](https://ahasend.com/docs/facts.md), [Product releases](https://ahasend.com/docs/changelog.md), [Tracking setup](https://ahasend.com/docs/tracking/open-tracking.md).
* [Sandbox behavior](https://ahasend.com/docs/send-api/sandbox.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.