# Quickstart

> Send your first email with the SendPing API in a few minutes.

## Prerequisites

1. A **verified domain** — add one under Domains and publish its DNS records. ([guide](https://www.sendping.co/docs/domains/managing))
2. An **API key** — create one under API Keys. It starts with `mb_` and is shown once. ([guide](https://www.sendping.co/docs/authentication))

## Install the SDK

Install the official SDK for your language — Node.js, Python, Ruby, PHP, Go, Rust, Java, .NET, or the CLI. Every install command is listed on [SDKs](https://www.sendping.co/docs/resources/sdks). The Node.js examples throughout these docs use the `sendping` npm package; each example also has tabs for the other packages and a dependency-free cURL tab if you prefer no SDK at all.

```sh
npm install sendping        # Node.js
pip install sendping        # Python
composer require sendping/sendping   # PHP
```

## Send an email

Replace `mb_xxxxxxxxx` with your API key and use a `from` address on your verified domain.

**Node.js**

```js
import { SendPing } from 'sendping';

const mb = new SendPing('mb_xxxxxxxxx');

const { data, error } = await mb.emails.send({
  "from": "Acme <hello@yourdomain.com>",
  "to": ["delivered@test.sendping.co"],
  "subject": "Hello from SendPing",
  "html": "<p>Your first email 🎉</p>"
});
console.log({ data, error });
```

**Ruby**

```ruby
require "sendping"

SendPing.api_key = "mb_xxxxxxxxx"

SendPing::Emails.send({
  "from": "Acme <hello@yourdomain.com>",
  "to": [
    "delivered@test.sendping.co"
  ],
  "subject": "Hello from SendPing",
  "html": "<p>Your first email 🎉</p>"
})
```

**PHP**

```php
<?php
require 'vendor/autoload.php';

use SendPing\SendPing;

$sendping = SendPing::client('mb_xxxxxxxxx');

$sendping->emails->send([
  'from' => "Acme <hello@yourdomain.com>",
  'to' => [
    "delivered@test.sendping.co"
  ],
  'subject' => "Hello from SendPing",
  'html' => "<p>Your first email 🎉</p>"
]);
```

**Python**

```python
import sendping

sendping.api_key = "mb_xxxxxxxxx"

sendping.Emails.send({
  "from": "Acme <hello@yourdomain.com>",
  "to": [
    "delivered@test.sendping.co"
  ],
  "subject": "Hello from SendPing",
  "html": "<p>Your first email 🎉</p>"
})
```

**Go**

```go
import "github.com/shekhu10/sendping-sdks/sendping-go"

client := sendping.NewClient("mb_xxxxxxxxx")

sent, err := client.Emails.Send(&sendping.SendEmailRequest{
    From:    "Acme <hello@yourdomain.com>",
    To:      []string{"delivered@test.sendping.co"},
    Subject: "Hello from SendPing",
    Html:    "<p>Your first email 🎉</p>",
})
```

**Rust**

```rust
use sendping::{SendEmailOptions, SendPing};

let mb = SendPing::new("mb_xxxxxxxxx");

let params = SendEmailOptions::new(
    "Acme <hello@yourdomain.com>",
    ["delivered@test.sendping.co"],
    "Hello from SendPing",
)
.with_html("<p>Your first email 🎉</p>");
let _sent = mb.emails.send(params).await?;
```

**Java**

```java
import co.sendping.SendPing;
import co.sendping.SendPingResponse;
import co.sendping.requests.SendEmailRequest;

SendPing sendping = new SendPing("mb_xxxxxxxxx");

SendEmailRequest request = SendEmailRequest.builder()
        .from("Acme <hello@yourdomain.com>")
        .to("delivered@test.sendping.co")
        .subject("Hello from SendPing")
        .html("<p>Your first email 🎉</p>")
        .build();

SendPingResponse response = sendping.emails().send(request);
```

**.NET**

```csharp
using SendPing;

ISendPing sendping = SendPingClient.Create("mb_xxxxxxxxx");

var resp = await sendping.EmailSendAsync(new EmailMessage
{
    From = "Acme <hello@yourdomain.com>",
    To = "delivered@test.sendping.co",
    Subject = "Hello from SendPing",
    HtmlBody = "<p>Your first email 🎉</p>",
});
```

**cURL**

```bash
curl -X POST 'https://www.sendping.co/api/emails' \
  -H 'Authorization: Bearer mb_xxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
  "from": "Acme <hello@yourdomain.com>",
  "to": ["delivered@test.sendping.co"],
  "subject": "Hello from SendPing",
  "html": "<p>Your first email 🎉</p>"
}'
```

**CLI**

```bash
sendping emails send \
  --from 'Acme <hello@yourdomain.com>' \
  --to 'delivered@test.sendping.co' \
  --subject 'Hello from SendPing' \
  --html '<p>Your first email 🎉</p>'
```

## Response

A successful send returns the email `id` you can use to [retrieve the email](https://www.sendping.co/docs/api/emails-get) or correlate webhook events.

```json
{
  "id": "49a3999c-0ce1-4ea6-ab68-afcd6dc2e794"
}
```

> **Warning:** If you get `validation_error` about the domain not being verified, finish the DNS verification first — emails can only be sent from a verified domain you own (or a subdomain of one).

## Test addresses

To simulate delivery events without sending to a real inbox (and without damaging your domain reputation), send to one of these reserved test recipients:

| Address | Simulates |
| --- | --- |
| `delivered@test.sendping.co` | A successful delivery. |
| `bounced@test.sendping.co` | A hard bounce. |
| `complained@test.sendping.co` | A spam complaint. |
| `suppressed@test.sendping.co` | A recipient on the suppression list. |

## Avoid duplicates with an idempotency key

To safely retry a send without delivering the same email twice, pass an `Idempotency-Key` header. A repeated request with the same key within the window returns the original result instead of sending again.

- Must be **unique per logical request**.
- Keys expire after **24 hours**.
- Maximum length **255 characters**.
- Recommended pattern: `<event-type>/<entity-id>` — for example `welcome-user/123456789`.

```bash
curl -X POST 'https://www.sendping.co/api/emails' \
  -H 'Authorization: Bearer mb_xxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: welcome-user/123456789' \
  -d '{
    "from": "Acme <hello@yourdomain.com>",
    "to": ["delivered@test.sendping.co"],
    "subject": "Hello from SendPing",
    "html": "<p>Your first email 🎉</p>"
  }'
```

## Next steps

- [Schedule an email](https://www.sendping.co/docs/emails/schedule) for later delivery.
- [Add attachments](https://www.sendping.co/docs/emails/attachments) or [custom headers](https://www.sendping.co/docs/emails/headers).
- [Send a batch](https://www.sendping.co/docs/emails/batch) of up to 100 emails in one request.
- [Receive webhooks](https://www.sendping.co/docs/webhooks/overview) for delivery and engagement events.