Skip to main content

​
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.

​
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: 
POST https://your-endpoint.com/send-email
Content-Type: application/json
Authorization: <your-auth-method>

​
Payload Structure (Minimal)

{
  "to": "[email protected]",
  "from": "Sender Name <[email protected]>",
  "content": {
    "subject": "Your email subject",
    "body": "<p>HTML email content</p>"
  },
  "metadata": {
    "message_id": "uuid-string"
  }
}

​
Field Reference

FieldTypeRequiredDescription
tostringYesRecipient email address
fromstringYesSender name and email address
content.subjectstringYesEmail subject line
content.bodystringYesEmail body in HTML format
metadataobjectNoAdditional data for tracking or debugging
metadata.message_idstringNoUnique 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): 
{
  "status": "accepted",
  "provider_message_id": "your-internal-id"
}
Error (4xx/5xx): 
{
  "status": "error",
  "message": "Description of what went wrong"
}

​
Example Implementation

Here’s a sample cURL request showing a common payload format: 
curl -X POST https://api.your-provider.com/send-email \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "to": "[email protected]",
    "from": "Acme Support <[email protected]>",
    "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 [email protected] for assistance with your custom integration.