Креирање и управување со вашиот API клуч

Published: 16 јули 2026 г. · Last updated: 21 јули 2026 г. · By Marcus Biel

Страницата „API Key“ му овозможува на надворешен систем автентициран пристап до поддржаните Maildroppa API-крајни точки во вашата сметка.

Можете да креирате еден API клуч, да ја копирате неговата целосна тајна вредност, безбедно да го ресетирате со ротирање или да го избришете кога повеќе не е потребен. Истиот клуч на сметката може да се користи за интеграции од страна на серверот и за активирачи на API-барања во Maildroppa Automations.

API клучот ја претставува вашата Maildroppa сметка. Третирајте го како лозинка: секој што ќе го добие клучот може да ги повикува API-крајните точки достапни за тој клуч сè додека не го ротирате или избришете.

За што служи API клучот

Користете го API клучот кога софтвер надвор од Maildroppa треба да работи со Maildroppa без интерактивно најавување на корисник.

Типични примери:

• Синхронизирање претплатници со CRM, продавница, членски систем или внатрешна база на податоци.
• Креирање или ажурирање претплатници од апликација на страна на серверот.
• Читање или управување со ознаки, полиња, вредности на полиња и сегменти преку поддржаните крајни точки.
• Испраќање сопствени настани до активирач на API-барање во Automation.
• Испраќање трансакциски Email Messages преку API.
• Управување со претплати на webhook-и базирани на API.

API клучот е наменет за комуникација од сервер до сервер. Не е наменет за код што работи во прелистувачот на посетителот, јавна веб-страница, мобилна апликација или вградена форма за пријавување.

Страницата моментално е означена како „beta“. Користете ја поврзаната OpenAPI документација како извор за крајните точки, телата на барањата, параметрите и шемите на одговорите што моментално ги поддржува API.

Отворање на страницата за API клучот

Отворете „Settings“, проширете „Developers“ и изберете „API key“.

Страницата можете да ја отворите и директно на:

https://app.maildroppa.com/settings/developers/api-key

Страницата содржи:

• Панел за API клучот со ознака beta.
• Врска „View OpenAPI docs“.
• Празна состојба и копче „Create API key“ кога не постои клуч.
• Маскирана претстава на тековниот клуч кога постои.
• Копче „Copy“ што го копира целосниот клуч.
• Дејства „Rotate API key“ и „Delete API key“ за замена или отстранување на тековниот клуч.

Maildroppa дозволува еден API клуч по сметка. Страницата не креира одделни клучеви за индивидуални апликации, околини или членови на тимот.

Креирање API клуч

Кога страницата прикажува „No API key yet“, кликнете „Create API key“.

Maildroppa го креира клучот веднаш. При ова прво креирање нема дијалог за потврда. Додека барањето се извршува, копчето се менува во „Creating API key“, а страницата привремено оневозможува дополнителни дејства со клучот.

Откако ќе се креира клучот:

• Празната состојба исчезнува.
• Се појавува маскиран клуч.
• Стануваат достапни дејствата „Copy“, „Rotate API key“ и „Delete API key“.
• Maildroppa прикажува порака за успешно „API key updated“.

Ако веќе постои друг клуч за сметката, Maildroppa нема да креира втор. Користете го постојниот клуч или ротирајте го.

Разбирање на маскираниот клуч

Страницата не ја прикажува целосната тајна како обичен текст. Ги прикажува првите пет знаци проследени со пет ѕвездички, на пример:

a1b2c*****

Ова е само визуелна маска. Ѕвездичките не ја претставуваат вистинската должина на клучот, а маскираната вредност не може да се користи за API-барање.

Кликнете „Copy“ за да го запишете целосниот тековен клуч во привремената меморија. По успешно копирање, копчето накратко се менува во „Copied!“.

Клучот останува маскиран кога ќе се вратите на страницата, но „Copy“ продолжува да ја копира целосната тековна вредност. Затоа не треба да ротирате важечки клуч само затоа што не сте го зачувале при креирањето.

Безбедно складирање на клучот

Пренесете го копираниот клуч директно во складиштето за тајни што го користи интеграцијата.

Соодветни места се:

• Управуван менаџер за тајни.
• Заштитена конфигурација на серверската околина.
• Шифрирана тајна за деплојмент.
• Менаџер за лозинки што се користи за оперативно обновување.

Не складирајте го клучот во:

• JavaScript на страната на прелистувачот или друг фронтенд пакет што може да се преземе.
• Јавна или приватна датотека со изворен код зачувана во складиште.
• URL или параметар за пребарување.
• Јавна документација, слики од екранот, пораки до поддршката или системи за следење на проблеми.
• Заеднички логови на апликацијата, аналитички настани или извештаи за грешки.
• Некриптирана табела или обичен тимски разговор.

Не додавајте го клучот во пример curl што ќе се копира во документација или во историја на школка споделена со други лица. Претпочитајте променлива на околината како MAILDROPPA_API_KEY.

Користење на API клучот

Испратете го целосниот клуч во HTTP заглавјето на барањето X-API-Key:

X-API-Key: your-complete-api-key

Не испраќајте го како Bearer токен. Maildroppa очекува X-API-Key, а не Authorization: Bearer ....

Продукциското API и неговата интерактивна OpenAPI документација се достапни на:

https://api.maildroppa.com

Кликнете „View OpenAPI docs“ на страницата за API клучот за да ја отворите документацијата во нов таб на прелистувачот. Таму изберете крајна точка за да ги разгледате нејзиниот метод, патека, параметри, тело на барањето, тип на одговор и можните статусни кодови.

Пример за барање

Следниот пример ја презема првата страница со претплатници. Го чита клучот од променлива на околината наместо тајната да ја става директно во командата:

curl --request GET \
  --url 'https://api.maildroppa.com/subscribers?pageNumber=1' \
  --header 'Accept: application/json' \
  --header "X-API-Key: ${MAILDROPPA_API_KEY}"

Поставете ја променливата во безбедната околина во која работи интеграцијата. Точниот метод, патека, параметри за пребарување и тело зависат од крајната точка. Копирајте ги тие детали од OpenAPI документацијата наместо да ги погодувате врз основа на дејствата достапни во апликацијата Maildroppa.

Барања со JSON тела

За барање што испраќа JSON, вклучете и:

Content-Type: application/json

На пример, основната структура е:

curl --request POST \
  --url 'https://api.maildroppa.com/example-endpoint' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "X-API-Key: ${MAILDROPPA_API_KEY}" \
  --data '{"example":"value"}'

/example-endpoint и неговото тело се само привремени вредности. Заменете ги со документирана крајна точка и нејзината документирана шема на барањето.

До што може да пристапи клучот

Клучот работи само со крајни точки што поддржуваат автентикација со API клуч. Страница или барање што се користи внатрешно од апликацијата Maildroppa автоматски не е дел од јавното API за корисници.

OpenAPI документацијата го прикажува поддржаното API за корисници. Ако патеката не е документирана за употреба со API клуч, не претпоставувајте дека клучот може да пристапи до неа.

Страницата за API клучот не нуди опсези или полиња за дозволи по крајна точка. Затоа со тековниот клуч на сметката треба да се постапува како со доверлив податок со висока вредност, дури и ако една интеграција користи само една крајна точка.

Ограничувања на брзината

Тековниот OpenAPI договор ги документира следните ограничувања за API клучот:

• Стандардно API за корисници: 300 барања во минута и 2.000 барања на час.
• Events API на /events: 100 барања во секунда со капацитет на краткотраен наплив од 500 барања.

Овие ограничувања се применуваат на Maildroppa сметката, а не независно на секоја скрипта што го споделува нејзиниот клуч. Затоа повеќе интеграции можат да го трошат истиот дозволен обем.

Кога Maildroppa ќе врати 429 Too Many Requests, престанете да испраќате нови барања и почитувајте го заглавјето за одговор Retry-After кога е присутно. Користете редица и контролирано постепено повторување наместо да започнувате многу паралелни обиди.

Политиките за ограничување на брзината може да се менуваат додека API е во beta. Проверете ги информациите на врвот на OpenAPI документацијата пред да дизајнирате интеграции со голем обем.

Користење на клучот за API-барања од Automation

Automation може да започне кога вашиот систем ќе испрати сопствен настан до Events API на Maildroppa.

Кога конфигурирате активирач „API request“, Maildroppa го користи истиот API клуч на сметката со кој се управува на оваа страница. Поставувањето на активирачот може да го креира клучот ако не постои и може да копира подготвено curl барање што го содржи целосниот клуч.

Ова има две важни последици:

• Ротирањето или бришењето на клучот на сметката влијае и на системите што испраќаат сопствени настани до Automations.
• Копираниот пример за Automation барање ја содржи тајната во привремената меморија иако клучот е маскиран на екранот.

Пред ротирање или бришење на клучот, внесете го секој активирач на API-барање и секој надворешен испраќач на настани во пописот на интеграции.

Ресетирање или замена на API клучот

Користете „Rotate API key“ кога треба да ја ресетирате или замените тековната доверлива информација. Maildroppa креира нов клуч и го поништува претходниот како дел од истото дејство.

Користете ротирање кога:

• Клучот можеби бил изложен.
• Лице или провајдер што го знаел клучот повеќе нема потреба од пристап.
• Вашата безбедносна политика бара периодична замена на доверливите информации.
• Сакате да замените клуч складиран на старо или небезбедно место.

Кликнете „Rotate API key“ под маскираниот клуч. Maildroppa отвора дијалог со предупредување дека постојниот клуч повеќе нема да може да се користи.

Кликнете „Rotate API key“ во дијалогот за да продолжите или кликнете „Cancel“ за да го задржите тековниот клуч.

Ротирањето нема период на одложено откажување

Откако ќе го потврдите ротирањето, стариот клуч престанува да работи веднаш. Maildroppa не ги одржува стариот и новиот клуч важечки истовремено.

Бидејќи сметката има само еден клуч, ротирањето влијае на секој сервер, закажана задача, интеграција, скрипта и испраќач на Automation настани што го користи.

Користете го следниот редослед за планирано ротирање:

1. Наведете ја секоја интеграција што го користи тековниот клуч.
2. Подгответе пристап до тајната конфигурација и процесот на деплојмент на секоја интеграција.
3. Изберете краток прозорец за одржување ако е важен непрекинатиот API пристап.
4. Кликнете „Rotate API key“, потоа потврдете го предупредувањето со „Rotate API key“ во дијалогот.
5. Кликнете „Copy“ за да го копирате целосниот нов клуч.
6. Веднаш заменете ја тајната во секоја интеграција.
7. Рестартирајте ги или повторно деплојирајте ги услугите што ги вчитуваат тајните само при стартување.
8. Испратете безопасно, документирано барање за да ја потврдите секоја интеграција.
9. Проверете дали има одговори 401 Unauthorized од заборавена услуга што сè уште го користи стариот клуч.

Ако се смета дека тековниот клуч е компромитиран, веднаш ротирајте го и прифатете го краткиот прекин потребен за ажурирање на легитимните системи.

Бришење на API клучот

Избришете го клучот кога сметката повеќе не треба да прифаќа барања автентицирани со API клуч.

Кликнете „Delete API key“ под маскираниот клуч. Maildroppa отвора дијалог со предупредување дека клучот трајно ќе биде отстранет од сметката.

Кликнете „Delete API key“ во дијалогот за да го избришете или кликнете „Cancel“ за да го задржите.

По бришењето:

• Тековниот клуч престанува да работи веднаш.
• Страницата се враќа во состојбата „No API key yet“.
• Интеграциите на серверот што го користат избришаниот клуч повеќе не можат да се автентицираат.
• Испраќачите на API-барања од Automation што го користат тој клуч повеќе не можат да доставуваат настани.

Бришењето клуч не брише претплатници, кампањи, ознаки, полиња, сегменти, Automations или други податоци на сметката. Тоа ја отстранува доверливата информација што се користи за пристап до поддржаните API-крајни точки.

Подоцна можете да кликнете „Create API key“ за да креирате нова доверлива информација. Избришаната вредност не се обновува. Секоја интеграција мора да се ажурира пред да може да го користи новиот клуч.

Ресетирање или бришење: што да изберете?

Изберете „Rotate API key“ кога API пристапот треба да продолжи со нова доверлива информација.

Изберете бришење кога API пристапот треба целосно да престане, барем засега.

Двете дејства веднаш го поништуваат тековниот клуч. Ротирањето создава замена како дел од истото дејство; бришењето ја остава сметката без клуч.

Безбедносни препораки

API-повикувањата нека останат на вашиот сервер

Прелистувач или мобилна апликација не може сигурно да чува вградена тајна. Корисник може да ја провери апликацијата, заглавјата на барањата, изворните мапи или мрежниот сообраќај и да го извлече клучот.

Ако веб-страница или апликација треба да активира дејство, прво испратете го барањето до сопствениот автентициран бекенд. Тој бекенд нека го потврди корисникот и нека го повика Maildroppa со клучот складиран на серверот.

Користете најмала можна изложеност

Дајте го клучот само на системи на кои им е потребен. Не дистрибуирајте го до секој развивач и не го вметнувајте во повеќе локални конфигурациски датотеки.

Бидејќи страницата моментално управува со еден клуч на ниво на сметка наместо со повеќе именувани или ограничени клучеви, користете внатрешна интеграциска услуга или прокси ако на повеќе апликации им е потребна посилна меѓусебна изолација.

Маскирајте ги заглавјата на барањата

Конфигурирајте ги HTTP-клиентите, обратните проксија, алатките за набљудување и известувачите за грешки да го маскираат X-API-Key. Барањето може да работи правилно, а сепак да ја открие доверливата информација преку дебагирачки логови.

Одржувајте ги одделните околини одделни

Не користете продукциски клуч во локален развој, примерен код, слики од екранот или тестни фикстури. Чувајте ги тајните специфични за околината во складишта за тајни специфични за околината.

Врската „View OpenAPI docs“ автоматски ги упатува продукциските корисници кон документацијата на продукциското API. Секогаш проверете го името на домаќинот пред да испратите вистински клуч.

Ротирајте по секое сомнение за изложеност

Бришењето порака, комит во складиште, линија во лог или слика од екранот не докажува дека никој не го копирал клучот. Ако целосната вредност била изложена, ротирајте го клучот.

Решавање API-грешки

Користете го HTTP статусот и документираното тело на одговорот за да одлучите што треба да направи интеграцијата.

Вообичаени случаи се:

• 400 Bad Request — Патеката, параметарот или JSON телото не го исполнува договорот на крајната точка. Споредете го барањето со OpenAPI шемата.
• 401 Unauthorized — Заглавјето X-API-Key недостасува, е празно, неважечко, избришано или содржи стара вредност по ротирање.
• 403 Forbidden — Автентицираниот клуч нема дозвола за таа операција.
• 404 Not Found — Патеката или референцираниот ресурс не постои во оваа сметка.
• 429 Too Many Requests — Интеграцијата достигнала ограничување на брзината на API. Паузирајте ги барањата и почитувајте го заглавјето Retry-After кога е присутно.
• 5xx — Maildroppa не можел да го заврши барањето. Повторувајте безбедни операции со ограничено експоненцијално постепено повторување и логирање што го исклучува API клучот.

Не повторувајте го секој неуспех без размислување. Исправете ги одговорите 400, 401, 403 и повеќето одговори 404 пред повторно да го испратите истото барање.

За барања што менуваат податоци, потврдете го однесувањето при повторување и идемпотентноста на крајната точка пред автоматски да го повторите барањето. Неуспехот на врската не докажува секогаш дека Maildroppa не извршил промена.

Решавање проблеми

„Create API key“ сè уште е видливо

Во сметката моментално не постои клуч. Кликнете го копчето еднаш и почекајте барањето да заврши.

Ако креирањето не успее, повторно вчитајте ја страницата пред повторен обид. Друга страница или поставување на Automation можеби веќе го креирало клучот на сметката.

Клучот на страницата изгледа прекраток

Страницата намерно ги прикажува само првите пет знаци и *****. Кликнете „Copy“ за да ја копирате целосната вредност. Не испраќајте го маскираниот текст во барање.

„Copy“ не се менува во „Copied!“

Прелистувачот можеби го блокирал пристапот до привремената меморија. Оставете ја страницата во активниот таб, дозволете пристап до привремената меморија ако се побара и повторно кликнете „Copy“.

Не обидувајте се да го реконструирате клучот од маскираниот текст.

Барањето враќа 401 Unauthorized

Проверете дали:

• Името на заглавјето е точно X-API-Key.
• Заглавјето ја содржи целосната вредност, без видливите ѕвездички.
• Интеграцијата не испраќа Authorization: Bearer наместо тоа.
• На тајната не ѝ се додадени празни места, наводници или нов ред.
• Никој не го ротирал или избришал клучот на сметката.
• Услугата е рестартирана ако ги чита променливите на околината само при стартување.
• Барањето се испраќа до точната Maildroppa API околина.

Една интеграција работи, но друга престана по ротирањето

Втората интеграција веројатно сè уште го користи стариот клуч. Нема период на преклопување. Ажурирајте ја нејзината тајна и рестартирајте го секој процес што ја кешира конфигурацијата.

OpenAPI страницата работи, но крајна точка враќа 403

Не секоја крајна точка на апликацијата поддржува автентикација со API клуч. Користете операција документирана за API за корисници и потврдете ги нејзините барања за автентикација на OpenAPI страницата.

Барањата враќаат 429 Too Many Requests

Намалете ги напливите на барања, ставете ја работата во редица и повторете по доцнењето што го враќа API. Избегнувајте бранови од паралелни повторувања. Ако повеќе апликации го споделуваат единствениот клуч на сметката, координирајте го обемот на нивните барања бидејќи ги споделуваат API ограничувањата на сметката.

Препорачана листа за проверка на поставувањето

Пред да ставите интеграција во редовна употреба, потврдете дека:

• Клучот е складиран само во серверска конфигурација за тајни.
• Барањата го користат заглавјето X-API-Key.
• Интеграцијата користи https://api.maildroppa.com во продукција.
• Секој метод, патека, параметар и JSON тело ја следи OpenAPI документацијата.
• Логовите и извештаите за грешки го маскираат клучот.
• Конфигурирани се истекувања и ограничени повторувања.
• Се следат 401, 403, 429 и серверските грешки.
• Евидентиран е сопственикот на интеграцијата.
• Секој систем што го споделува клучот на сметката е вклучен во планот за ротирање.
• Компромитиран клуч може брзо да се ротира.

Страницата за API клучот е намерно мала, но нејзините дејства влијаат на секоја API интеграција поврзана со сметката. Креирајте го клучот само кога е потребен, чувајте го на доверливи сервери и планирајте го ротирањето како промена на доверлива информација на ниво на целата сметка.