Уншиж байна...
түр хүлээнэ үү...
Maildy-ийн Захиалагч API нь и-мэйл захиалагчдаа программаар удирдах боломжийг олгоно. Энгийн REST API дуудлагаар жагсаалт дахь захиалагчдаа үүсгэх, татах, шинэчлэх, хайх боломжтой.
Бүх API хүсэлт Bearer токен ашиглан баталгаажуулалт шаарддаг. Хүсэлт илгээхээсээ өмнө Maildy бүртгэлдээ API түлхүүр үүсгэх шаардлагатай.
Хүсэлт бүрийн Authorization header-д API түлхүүрээ оруулна уу:
Authorization: Bearer ТАНЫ_API_ТҮЛХҮҮР
Аюулгүй байдлын тэмдэглэл: API түлхүүрээ клиентийн талын код эсвэл олон нийтийн репозитод хэзээ ч задруулж болохгүй.
https://app.maildy.mn/api/v1/lists/{listId}/subscribers
Бүх захиалагчийн endpoint-ууд тодорхой жагсаалтад хамаарна. {listId}-г өөрийн жагсаалтын ID-аар солино уу.
| Арга | Endpoint | Тайлбар |
|---|---|---|
POST | /api/v1/lists/{listId}/subscribers | Шинэ захиалагч үүсгэх |
GET | /api/v1/lists/{listId}/subscribers/{subscriberId} | ID-аар захиалагч татах |
GET | /api/v1/lists/{listId}/subscribers/email/{email} | И-мэйлээр захиалагч татах |
POST | /api/v1/lists/{listId}/subscribers/search | Захиалагч хайх |
PUT | /api/v1/lists/{listId}/subscribers/{subscriberId} | Захиалагч шинэчлэх |
POST | /api/v1/lists/{listId}/subscribers/{subscriberId}/unsubscribe | Захиалгаа цуцлах |
API нь стандарт HTTP статус кодуудыг ашигладаг:
| Статус код | Тайлбар |
|---|---|
200 OK | Хүсэлт амжилттай |
201 Created | Нөөц амжилттай үүссэн |
400 Bad Request | Буруу хүсэлтийн параметр |
401 Unauthorized | API түлхүүр байхгүй эсвэл буруу |
404 Not Found | Нөөц олдсонгүй |
409 Conflict | Нөөц аль хэдийн байна |
429 Too Many Requests | Хүсэлтийн хязгаар давсан |
500 Internal Server Error | Серверийн алдаа |
Алдааны хариунууд дэлгэрэнгүй мэдээлэл бүхий JSON агуулна:
{
"error": {
"code": "subscriber_exists",
"message": "Захиалагч аль хэдийн байна. Дахин идэвхжүүлэхийн тулд reactivateExisting=true тохируулна уу.",
"details": {}
}
}
POST /api/v1/lists/{listId}/subscribers
Creates a new subscriber in your list. If the email already exists and reactivateExisting is true, the subscriber will be reactivated.
{
"email": "subscriber@example.com",
"firstName": "Steve",
"lastName": "Wozniak",
"phone": "+97699123456",
"reactivateExisting": false,
"sendWelcomeEmail": true,
"utmSource": "website",
"utmMedium": "organic",
"utmCampaign": "spring_2025",
"referringSite": "https://example.com/blog",
"referralCode": "REF123",
"customFields": {
"company": "Apple",
"role": "Engineer"
},
"tags": ["vip", "early-access"],
"country": "MN",
"city": "Ulaanbaatar",
"ipAddress": "203.91.112.10"
}
| Parameter | Type | Required | Description |
|---|---|---|---|
email | string | Yes | Subscriber's email address |
firstName | string | No | First name |
lastName | string | No | Last name |
phone | string | No | Phone number with country code |
reactivateExisting | boolean | No | If true, reactivates unsubscribed subscribers |
sendWelcomeEmail | boolean | No | If true, sends welcome email |
utmSource | string | No | UTM source for tracking |
utmMedium | string | No | UTM medium for tracking |
utmCampaign | string | No | UTM campaign for tracking |
referringSite | string | No | Referring website URL |
referralCode | string | No | Referral code |
customFields | object | No | Key-value pairs of custom fields |
tags | array | No | Array of tag strings |
country | string | No | ISO 2-letter country code |
city | string | No | City name |
ipAddress | string | No | IP address |
{
"id": 12345,
"email": "subscriber@example.com",
"firstName": "Steve",
"lastName": "Wozniak",
"phone": "+97699123456",
"status": "active",
"createdAt": "2025-11-28T10:30:00Z",
"updatedAt": "2025-11-28T10:30:00Z",
"utmSource": "website",
"utmMedium": "organic",
"utmCampaign": "spring_2025",
"referringSite": "https://example.com/blog",
"referralCode": "REF123",
"customFields": {
"company": "Apple",
"role": "Engineer"
},
"tags": ["vip", "early-access"],
"stats": {
"emailsReceived": 0,
"openRate": 0.0,
"clickThroughRate": 0.0
}
}
const response = await fetch('https://app.maildy.mn/api/v1/lists/42/subscribers', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
email: 'subscriber@example.com',
firstName: 'Steve',
lastName: 'Wozniak',
sendWelcomeEmail: true,
utmSource: 'website',
customFields: {
company: 'Apple'
},
tags: ['vip']
})
});
const data = await response.json();
console.log(data);
import requests
url = "https://app.maildy.mn/api/v1/lists/42/subscribers"
payload = {
"email": "subscriber@example.com",
"firstName": "Steve",
"lastName": "Wozniak",
"sendWelcomeEmail": True,
"utmSource": "website",
"customFields": {
"company": "Apple"
},
"tags": ["vip"]
}
headers = {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
curl -X POST https://app.maildy.mn/api/v1/lists/42/subscribers \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"email": "subscriber@example.com",
"firstName": "Steve",
"lastName": "Wozniak",
"sendWelcomeEmail": true,
"utmSource": "website",
"customFields": {
"company": "Apple"
},
"tags": ["vip"]
}'
import java.net.http.*;
import java.net.URI;
HttpClient client = HttpClient.newHttpClient();
String json = """
{
"email": "subscriber@example.com",
"firstName": "Steve",
"lastName": "Wozniak",
"sendWelcomeEmail": true,
"utmSource": "website",
"customFields": {
"company": "Apple"
},
"tags": ["vip"]
}
""";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://app.maildy.mn/api/v1/lists/42/subscribers"))
.header("Authorization", "Bearer YOUR_API_KEY")
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(json))
.build();
HttpResponse<String> response = client.send(request,
HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
<?php
$client = new \GuzzleHttp\Client();
$response = $client->request('POST',
'https://app.maildy.mn/api/v1/lists/42/subscribers', [
'json' => [
'email' => 'subscriber@example.com',
'firstName' => 'Steve',
'lastName' => 'Wozniak',
'sendWelcomeEmail' => true,
'utmSource' => 'website',
'customFields' => [
'company' => 'Apple'
],
'tags' => ['vip']
],
'headers' => [
'Authorization' => 'Bearer YOUR_API_KEY',
'Content-Type' => 'application/json',
],
]);
echo $response->getBody();
package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
)
func main() {
url := "https://app.maildy.mn/api/v1/lists/42/subscribers"
payload := map[string]interface{}{
"email": "subscriber@example.com",
"firstName": "Steve",
"lastName": "Wozniak",
"sendWelcomeEmail": true,
"utmSource": "website",
"customFields": map[string]string{
"company": "Apple",
},
"tags": []string{"vip"},
}
jsonData, _ := json.Marshal(payload)
req, _ := http.NewRequest("POST", url, bytes.NewBuffer(jsonData))
req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()
fmt.Println(resp.Status)
}
GET /api/v1/lists/{listId}/subscribers/{subscriberId}
Retrieves a specific subscriber by their ID.
| Parameter | Type | Required | Description |
|---|---|---|---|
listId | integer | Yes | Your list ID |
subscriberId | integer | Yes | Subscriber ID |
{
"id": 12345,
"email": "subscriber@example.com",
"firstName": "Steve",
"lastName": "Wozniak",
"status": "active",
"createdAt": "2025-11-28T10:30:00Z",
"stats": {
"emailsReceived": 45,
"openRate": 68.5,
"clickThroughRate": 12.3
}
}
const response = await fetch(
'https://app.maildy.mn/api/v1/lists/42/subscribers/12345',
{
headers: {
'Authorization': 'Bearer YOUR_API_KEY'
}
}
);
const subscriber = await response.json();
curl -X GET https://app.maildy.mn/api/v1/lists/42/subscribers/12345 \
-H "Authorization: Bearer YOUR_API_KEY"
import requests
url = "https://app.maildy.mn/api/v1/lists/42/subscribers/12345"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
response = requests.get(url, headers=headers)
print(response.json())
POST /api/v1/lists/{listId}/subscribers/search
Search and filter subscribers with pagination support.
{
"status": "active",
"email": "steve",
"tag": "vip",
"utmSource": "website",
"createdAfter": "2025-01-01T00:00:00Z"
}
| Parameter | Type | Description |
|---|---|---|
page | integer | Page number (default: 0) |
size | integer | Items per page (default: 50, max: 100) |
sort | string | Sort field and direction (e.g., "createdAt,desc") |
{
"content": [
{
"id": 12345,
"email": "subscriber@example.com",
"status": "active"
}
],
"page": 0,
"size": 50,
"totalElements": 1250,
"totalPages": 25
}
PUT /api/v1/lists/{listId}/subscribers/{subscriberId}
Updates an existing subscriber's information.
Same as Create Subscriber endpoint. Only provided fields will be updated.
POST /api/v1/lists/{listId}/subscribers/{subscriberId}/unsubscribe
Unsubscribes a subscriber from the list.
204 No Content - Successfully unsubscribed
| Status | Description |
|---|---|
pending | Awaiting email confirmation (double opt-in) |
active | Active subscriber receiving emails |
unsubscribed | Opted out from receiving emails |
bounced | Email address bounced |
Always check for existing subscribers before creating new ones. Set reactivateExisting: true if you want to reactivate unsubscribed users.
// Check if subscriber exists first
const checkResponse = await fetch(
`https://app.maildy.mn/api/v1/lists/42/subscribers/email/${email}`,
{
headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
}
);
if (checkResponse.status === 404) {
// Subscriber doesn't exist, create new one
await createSubscriber(email);
}
Use UTM parameters to track subscriber sources:
{
"email": "user@example.com",
"utmSource": "facebook",
"utmMedium": "cpc",
"utmCampaign": "spring_sale_2025"
}
Store additional data about your subscribers:
{
"email": "user@example.com",
"customFields": {
"company": "Acme Inc",
"jobTitle": "Marketing Director",
"employees": "51-200",
"industry": "Technology"
}
}
When searching large lists, use pagination to avoid timeouts:
let page = 0;
const size = 100;
let hasMore = true;
while (hasMore) {
const response = await fetch(
`https://app.maildy.mn/api/v1/lists/42/subscribers/search?page=${page}&size=${size}`,
{
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({ status: 'active' })
}
);
const data = await response.json();
// Process data.content
hasMore = page < data.totalPages - 1;
page++;
}
Always implement proper error handling:
try {
const response = await fetch(url, options);
if (!response.ok) {
const error = await response.json();
console.error('API Error:', error);
throw new Error(error.message);
}
return await response.json();
} catch (error) {
console.error('Request failed:', error);
// Implement retry logic or notify user
}
Use our sandbox environment for testing:
https://sandbox.maildy.mn/api/v1/lists/{listId}/subscribers
Sandbox features: