Създаване и управление на вашия API ключ

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

Страницата „API key“ предоставя на външна система удостоверен достъп до поддържаните API крайни точки на Maildroppa във вашия акаунт.

Можете да създадете един API ключ, да копирате пълната му секретна стойност, да го нулирате безопасно чрез ротация или да го изтриете, когато вече не е необходим. Един и същ ключ за акаунта може да се използва от сървърни интеграции и от тригери за API заявки в Maildroppa Automations.

API ключът представлява вашия акаунт в Maildroppa. Третирайте го като парола: всеки, който се сдобие с ключа, може да извиква наличните за него API крайни точки, докато не го ротирате или изтриете.

За какво служи API ключът

Използвайте API ключа, когато софтуер извън Maildroppa трябва да работи с Maildroppa без интерактивно влизане на потребител.

Типичните примери включват:

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

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 от страната на браузъра или друг изтегляем frontend bundle.
• Публичен или частен файл с изходен код, добавен към хранилище.
• URL адрес или query параметър.
• Публична документация, екранни снимки, съобщения до поддръжката или системи за проследяване на проблеми.
• Споделени логове на приложения, аналитични събития или отчети за грешки.
• Некриптирана електронна таблица или обикновен екипен чат.

Не добавяйте ключа в пример с curl, който ще бъде копиран в документация или споделена с други хора shell история. Предпочитайте променлива на средата като MAILDROPPA_API_KEY.

Използване на API ключа

Изпращайте пълния ключ в HTTP заглавката на заявката X-API-Key:

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

Не го изпращайте като Bearer token. 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}"

Задайте променливата в защитената среда, в която се изпълнява интеграцията. Точният метод, път, query параметри и тяло зависят от крайната точка. Копирайте тези подробности от 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, не е автоматично част от публичния customer API.

OpenAPI документацията показва поддържания customer API. Ако даден път не е документиран за използване с API ключ, не приемайте, че ключът има достъп до него.

Страницата за API ключа не предлага scopes или отметки за разрешения по крайни точки. Затова текущият ключ на акаунта трябва да се третира като високостойностна идентификационна информация, дори ако една интеграция използва само една крайна точка.

Ограничения на честотата

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

• Default customer API: 300 заявки в минута и 2 000 заявки на час.
• Events API на /events: 100 заявки в секунда с burst капацитет от 500 заявки.

Тези ограничения се прилагат към акаунта в Maildroppa, а не независимо към всеки скрипт, който споделя ключа. Следователно няколко интеграции могат да изразходват една и съща квота.

Когато Maildroppa върне 429 Too Many Requests, спрете изпращането на нови заявки и спазвайте заглавката на отговора Retry-After, когато е налична. Използвайте опашка и контролиран backoff, вместо да стартирате много паралелни повторни опити.

Политиките за ограниченията могат да се променят, докато 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“.
• Сървърните интеграции, използващи изтрития ключ, повече не могат да се удостоверяват.
• Изпращачите на Automation API заявки, използващи този ключ, повече не могат да доставят събития.

Изтриването на ключ не изтрива абонати, кампании, тагове, полета, сегменти, Automations или други данни в акаунта. То премахва идентификационните данни, използвани за достъп до поддържаните API крайни точки.

По-късно можете да натиснете „Create API key“, за да създадете нови идентификационни данни. Изтритата стойност не се възстановява. Всяка интеграция трябва да бъде актуализирана, преди да може да използва новия ключ.

Нулиране или изтриване: кое да изберете?

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

Изберете изтриване, когато API достъпът трябва да бъде напълно спрян, поне засега.

И двете действия обезсилват текущия ключ незабавно. Ротацията създава заместващ ключ като част от същото действие; изтриването оставя акаунта без ключ.

Препоръки за сигурност

Дръжте API повикванията на сървъра си

Браузър или мобилно приложение не могат надеждно да пазят вграден секрет. Потребителят може да инспектира приложението, заглавките на заявките, source maps или мрежовия трафик и да извлече ключа.

Ако уебсайт или приложение трябва да задейства действие, първо изпратете заявката към собствен backend с удостоверяване. Нека този backend валидира потребителя и извика Maildroppa с ключа, съхраняван на сървъра.

Използвайте възможно най-малка експозиция

Предоставяйте ключа само на системи, които се нуждаят от него. Не го разпространявайте до всеки разработчик и не го поставяйте в множество локални конфигурационни файлове.

Тъй като страницата в момента управлява един ключ за целия акаунт, а не множество именувани или ограничени ключове, използвайте вътрешна интеграционна услуга или proxy, ако няколко приложения се нуждаят от по-силна изолация едно от друго.

Маскирайте заглавките на заявките

Конфигурирайте HTTP клиенти, reverse proxy сървъри, инструменти за наблюдение и системи за отчитане на грешки да маскират X-API-Key. Заявката може да работи правилно, но въпреки това да изтече идентификационната ѝ информация чрез debug логове.

Поддържайте отделни среди

Не използвайте повторно продукционен ключ в локална разработка, примерен код, екранни снимки или тестови фикстури. Съхранявайте специфичните за средата секрети в специфични за средата хранилища за секрети.

Връзката „View OpenAPI docs“ автоматично насочва продукционните потребители към документацията на продукционния API. Винаги проверявайте hostname преди да изпратите реален ключ.

Ротирайте след всяко предполагаемо разкриване

Изтриването на съобщение, commit в хранилище, ред от лог или екранна снимка не доказва, че никой не е копирал ключа. Ако пълната стойност е била разкрита, ротирайте я.

Обработка на 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 не е успял да изпълни заявката. Повтаряйте безопасни операции с ограничен експоненциален backoff и логване, което не включва API ключа.

Не повтаряйте сляпо всеки неуспешен опит. Коригирайте отговорите 400, 401, 403 и повечето отговори 404, преди да изпратите същата заявка отново.

При заявки, които променят данни, потвърдете поведението на крайната точка при повторен опит и нейната idempotency политика, преди автоматично да повтаряте заявка. Прекъсването на връзката не винаги доказва, че Maildroppa не е извършил промяна.

Отстраняване на неизправности

„Create API key“ все още се вижда

В акаунта в момента няма ключ. Натиснете бутона веднъж и изчакайте заявката да приключи.

Ако създаването е неуспешно, презаредете страницата, преди да опитате отново. Друга страница или настройка на Automation може вече да е създала ключа на акаунта.

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

Страницата умишлено показва само първите пет знака и *****. Натиснете „Copy“, за да копирате пълната стойност. Не изпращайте маскирания текст в заявка.

„Copy“ не се променя на „Copied!“

Браузърът може да е блокирал достъпа до клипборда. Оставете страницата в активния раздел, разрешете достъпа до клипборда, ако бъдете подканени, и натиснете „Copy“ отново.

Не се опитвайте да възстановите ключа от маскирания текст.

Заявка връща 401 Unauthorized

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

• Името на заглавката е точно X-API-Key.
• Заглавката съдържа пълната стойност, без видимите звездички.
• Интеграцията не изпраща Authorization: Bearer вместо това.
• Към секрета не са добавени интервали, кавички или нов ред.
• Никой не е ротирал или изтрил ключа на акаунта.
• Услугата е рестартирана, ако чете променливите на средата само при стартиране.
• Заявката се изпраща към правилната API среда на Maildroppa.

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

Втората интеграция вероятно все още използва стария ключ. Няма период на припокриване. Актуализирайте секрета ѝ и рестартирайте всеки процес, който кешира конфигурацията.

Страницата OpenAPI работи, но крайна точка връща 403

Не всяка крайна точка на приложението поддържа удостоверяване чрез API ключ. Използвайте операция, документирана за customer API, и потвърдете изискванията ѝ за удостоверяване в страницата OpenAPI.

Заявките връщат 429 Too Many Requests

Намалете burst-овете от заявки, поставете работата на опашка и повторете след забавянето, върнато от API. Избягвайте паралелни вълни от повторни опити. Ако няколко приложения споделят един ключ на акаунта, координирайте обема им от заявки, защото споделят API ограниченията на акаунта.

Препоръчителен контролен списък за настройка

Преди да въведете интеграция в редовна употреба, потвърдете, че:

• Ключът се съхранява само в сървърна конфигурация за секрети.
• Заявките използват заглавката X-API-Key.
• Интеграцията използва https://api.maildroppa.com в продукция.
• Всеки метод, път, параметър и JSON тяло следва OpenAPI документацията.
• Логовете и отчетите за грешки маскират ключа.
• Конфигурирани са timeout-и и ограничени повторни опити.
• Наблюдават се 401, 403, 429 и сървърните грешки.
• Собственикът на интеграцията е записан.
• Всяка система, която споделя ключа на акаунта, е включена в плана за ротация.
• Компрометиран ключ може да бъде ротиран бързо.

Страницата за API ключа умишлено е малка, но действията ѝ засягат всяка API интеграция, свързана с акаунта. Създавайте ключа само когато е необходим, пазете го на доверени сървъри и планирайте ротацията като промяна на идентификационните данни за целия акаунт.