Уншиж байна...

түр хүлээнэ үү...

Захиалагч API

Maildy-ийн REST API ашиглан захиалагчдыг программаар удирдах бүрэн гарын авлага.

Maildy-ийн Захиалагч API нь и-мэйл захиалагчдаа программаар удирдах боломжийг олгоно. Энгийн REST API дуудлагаар жагсаалт дахь захиалагчдаа үүсгэх, татах, шинэчлэх, хайх боломжтой.

Баталгаажуулалт

Бүх API хүсэлт Bearer токен ашиглан баталгаажуулалт шаарддаг. Хүсэлт илгээхээсээ өмнө Maildy бүртгэлдээ API түлхүүр үүсгэх шаардлагатай.

API түлхүүр авах

  1. Maildy бүртгэлдээ нэвтэрнэ үү
  2. ТохиргооAPI түлхүүрүүд руу очино уу
  3. Шинэ API түлхүүр үүсгэх дарна уу
  4. API түлхүүрээ хуулж аюулгүй хадгална уу

Баталгаажсан хүсэлт илгээх

Хүсэлт бүрийн Authorization header-д API түлхүүрээ оруулна уу:

Authorization: Bearer ТАНЫ_API_ТҮЛХҮҮР

Аюулгүй байдлын тэмдэглэл: API түлхүүрээ клиентийн талын код эсвэл олон нийтийн репозитод хэзээ ч задруулж болохгүй.

Суурь URL

https://app.maildy.mn/api/v1/lists/{listId}/subscribers

Бүх захиалагчийн endpoint-ууд тодорхой жагсаалтад хамаарна. {listId}-г өөрийн жагсаалтын ID-аар солино уу.

API Endpoint-ууд

Арга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 түлхүүр тус бүрт минутанд 100 хүсэлт
  • API түлхүүр тус бүрт өдөрт 10,000 хүсэлт
  • Хүсэлтийн хязгаарын header нь хариу бүрт багтана

Алдааны боловсруулалт

API нь стандарт HTTP статус кодуудыг ашигладаг:

Статус кодТайлбар
200 OKХүсэлт амжилттай
201 CreatedНөөц амжилттай үүссэн
400 Bad RequestБуруу хүсэлтийн параметр
401 UnauthorizedAPI түлхүүр байхгүй эсвэл буруу
404 Not FoundНөөц олдсонгүй
409 ConflictНөөц аль хэдийн байна
429 Too Many RequestsХүсэлтийн хязгаар давсан
500 Internal Server ErrorСерверийн алдаа

Алдааны хариунууд дэлгэрэнгүй мэдээлэл бүхий JSON агуулна:

{
  "error": {
    "code": "subscriber_exists",
    "message": "Захиалагч аль хэдийн байна. Дахин идэвхжүүлэхийн тулд reactivateExisting=true тохируулна уу.",
    "details": {}
  }
}

Create Subscriber

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.

Request Body

{
  "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"
}

Parameters

ParameterTypeRequiredDescription
emailstringYesSubscriber's email address
firstNamestringNoFirst name
lastNamestringNoLast name
phonestringNoPhone number with country code
reactivateExistingbooleanNoIf true, reactivates unsubscribed subscribers
sendWelcomeEmailbooleanNoIf true, sends welcome email
utmSourcestringNoUTM source for tracking
utmMediumstringNoUTM medium for tracking
utmCampaignstringNoUTM campaign for tracking
referringSitestringNoReferring website URL
referralCodestringNoReferral code
customFieldsobjectNoKey-value pairs of custom fields
tagsarrayNoArray of tag strings
countrystringNoISO 2-letter country code
citystringNoCity name
ipAddressstringNoIP address

Response

{
  "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
  }
}

Code Examples

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);

Get Subscriber

GET /api/v1/lists/{listId}/subscribers/{subscriberId}

Retrieves a specific subscriber by their ID.

Path Parameters

ParameterTypeRequiredDescription
listIdintegerYesYour list ID
subscriberIdintegerYesSubscriber ID

Response

{
  "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
  }
}

Code Examples

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();

Search Subscribers

POST /api/v1/lists/{listId}/subscribers/search

Search and filter subscribers with pagination support.

Request Body

{
  "status": "active",
  "email": "steve",
  "tag": "vip",
  "utmSource": "website",
  "createdAfter": "2025-01-01T00:00:00Z"
}

Query Parameters

ParameterTypeDescription
pageintegerPage number (default: 0)
sizeintegerItems per page (default: 50, max: 100)
sortstringSort field and direction (e.g., "createdAt,desc")

Response

{
  "content": [
    {
      "id": 12345,
      "email": "subscriber@example.com",
      "status": "active"
    }
  ],
  "page": 0,
  "size": 50,
  "totalElements": 1250,
  "totalPages": 25
}

Update Subscriber

PUT /api/v1/lists/{listId}/subscribers/{subscriberId}

Updates an existing subscriber's information.

Request Body

Same as Create Subscriber endpoint. Only provided fields will be updated.


Unsubscribe

POST /api/v1/lists/{listId}/subscribers/{subscriberId}/unsubscribe

Unsubscribes a subscriber from the list.

Response

204 No Content - Successfully unsubscribed


Subscriber Status Values

StatusDescription
pendingAwaiting email confirmation (double opt-in)
activeActive subscriber receiving emails
unsubscribedOpted out from receiving emails
bouncedEmail address bounced

Best Practices

Handling Duplicates

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);
}

UTM Tracking

Use UTM parameters to track subscriber sources:

{
  "email": "user@example.com",
  "utmSource": "facebook",
  "utmMedium": "cpc",
  "utmCampaign": "spring_sale_2025"
}

Custom Fields

Store additional data about your subscribers:

{
  "email": "user@example.com",
  "customFields": {
    "company": "Acme Inc",
    "jobTitle": "Marketing Director",
    "employees": "51-200",
    "industry": "Technology"
  }
}

Pagination

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++;
}

Error Handling

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
}

Testing

Use our sandbox environment for testing:

https://sandbox.maildy.mn/api/v1/lists/{listId}/subscribers

Sandbox features:

  • Separate from production data
  • No emails actually sent
  • Reset anytime
  • Same API interface

Need Help?