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

# Custom API

> Aampe guidelines for all the one-of-a-kind message providers

## Custom Email Provider

Connect Aampe to your own email infrastructure when you need full control over delivery or when using an email provider not yet supported by [Aampe's native integrations](/developer-guide/message-providers/message-providers).

## Requirements

Aampe will need the following in order to deliver messages on your behalf:

* A publicly accessible HTTP endpoint that accepts POST requests
* An authentication method (API key, Bearer token, or custom header)
* The ability to process JSON payloads and return JSON responses

## API Contract

Your endpoint should implement the following contract for Aampe to successfully deliver email messages.

### Request Format

Aampe sends a `POST` request with the following headers:

```text theme={null}
POST https://your-endpoint.com/send-email
Content-Type: application/json
Authorization: <your-auth-method>
```

### Payload Structure (Minimal)

```text theme={null}
{
  "to": "recipient@example.com",
  "from": "Sender Name <sender@example.com>",
  "content": {
    "subject": "Your email subject",
    "body": "<p>HTML email content</p>"
  },
  "metadata": {
    "message_id": "uuid-string"
  }
}
```

### Field Reference

| Field                 | Type   | Required | Description                               |
| :-------------------- | :----- | :------- | :---------------------------------------- |
| `to`                  | string | Yes      | Recipient email address                   |
| `from`                | string | Yes      | Sender name and email address             |
| `content.subject`     | string | Yes      | Email subject line                        |
| `content.body`        | string | Yes      | Email body in HTML format                 |
| `metadata`            | object | No       | Additional data for tracking or debugging |
| `metadata.message_id` | string | No       | Unique identifier for the message         |

> **Note:** The `body` field contains HTML content. Plain text fallback support is optional on your end.

### Response Format

Your endpoint should return JSON responses with appropriate HTTP status codes.

**Success (200 OK):**

```text theme={null}
{
  "status": "accepted",
  "provider_message_id": "your-internal-id"
}
```

**Error (4xx/5xx):**

```text theme={null}
{
  "status": "error",
  "message": "Description of what went wrong"
}
```

## Example Implementation

Here's a sample cURL request showing a common payload format:

```text theme={null}
curl -X POST https://api.your-provider.com/send-email \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "to": "john.doe@example.com",
    "from": "Acme Support <support@acme.com>",
    "content": {
      "subject": "Order Confirmation",
      "body": "<p>Hi John,<br/>Your order has been confirmed.</p>"
    },
    "metadata": {
      "message_id": "b3b1c2e4-8f12-4c9a-9a0d-acde12345678"
    }
  }'
```

## Troubleshooting

**Connection test fails**

* Verify your endpoint is publicly accessible (not behind a firewall or VPN)
* Check that your authentication credentials are correct
* Ensure your endpoint returns valid JSON responses

**Messages not delivering**

* Confirm your endpoint returns a `200 OK` status for successful requests
* Check your endpoint logs for incoming requests from Aampe
* Verify the `provider_message_id` is being returned in successful responses

**Need help?** Contact your Aampe representative or email [support@aampe.com](mailto:support@aampe.com) for assistance with your custom integration.