Створення та керування API-ключем

Published: 16 липня 2026 р. · Last updated: 21 липня 2026 р. · By Marcus Biel

Сторінка API-ключа надає зовнішній системі автентифікований доступ до підтримуваних кінцевих точок API Maildroppa у вашому обліковому записі.

Ви можете створити один API-ключ, скопіювати його повне секретне значення, безпечно скинути його шляхом ротації або видалити, коли він більше не потрібен. Один і той самий ключ облікового запису можна використовувати для серверних інтеграцій і тригерів API-запитів в автоматизаціях Maildroppa.

API-ключ представляє ваш обліковий запис Maildroppa. Ставтеся до нього як до пароля: будь-хто, хто отримає ключ, зможе викликати доступні для цього ключа кінцеві точки API, доки ви не ротуватимете або не видалите його.

Для чого потрібен API-ключ

Використовуйте API-ключ, коли програмному забезпеченню за межами Maildroppa потрібно взаємодіяти з Maildroppa без інтерактивного входу користувача.

Типові приклади:

• Синхронізація підписників із CRM, магазином, системою членства або внутрішньою базою даних.
• Створення або оновлення підписників із серверного застосунку.
• Читання або керування тегами, полями, значеннями полів і сегментами через підтримувані кінцеві точки.
• Надсилання власних подій до тригера API-запиту в автоматизації.
• Надсилання транзакційних Email Messages через API.
• Керування підписками на вебхуки через 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 на стороні браузера або іншому доступному для завантаження frontend-бандлі.
• Загальнодоступному чи приватному файлі вихідного коду, зафіксованому в репозиторії.
• 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-запитів автоматизацій

Автоматизація може запускатися, коли ваша система надсилає власну подію до Events API Maildroppa.

Коли ви налаштовуєте тригер «API request», Maildroppa використовує той самий API-ключ облікового запису, яким керують на цій сторінці. Налаштування тригера може створити ключ, якщо його немає, і скопіювати підготовлений запит curl, що містить повний ключ.

Це має два важливі наслідки:

• Ротація або видалення ключа облікового запису також впливає на системи, які надсилають власні події до автоматизацій.
• Скопійований приклад запиту автоматизації містить секрет у буфері обміну, хоча на екрані ключ замаскований.

Перед ротацією або видаленням ключа додайте до переліку інтеграцій кожен тригер API-запиту та кожного зовнішнього відправника подій.

Скидання або заміна API-ключа

Використовуйте «Rotate API key», коли потрібно скинути або замінити поточні облікові дані. Maildroppa створює новий ключ і в межах тієї самої дії робить попередній недійсним.

Виконуйте ротацію, коли:

• Ключ міг бути розкритий.
• Особа або постачальник, які знали ключ, більше не потребують доступу.
• Ваша політика безпеки вимагає періодичної заміни облікових даних.
• Ви хочете замінити ключ, збережений у старому або небезпечному місці.

Натисніть «Rotate API key» під замаскованим ключем. Maildroppa відкриє попереджувальне діалогове вікно з поясненням, що наявний ключ більше не можна буде використовувати.

Натисніть «Rotate API key» у діалоговому вікні, щоб продовжити, або «Cancel», щоб залишити поточний ключ.

Ротація не має пільгового періоду

Після підтвердження ротації старий ключ негайно припиняє працювати. Maildroppa не залишає старий і новий ключі дійсними одночасно.

Оскільки обліковий запис має лише один ключ, ротація впливає на кожен сервер, заплановане завдання, інтеграцію, скрипт і відправника подій автоматизації, який його використовує.

Для запланованої ротації використовуйте таку послідовність:

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-запитів автоматизацій, які використовують цей ключ, більше не можуть доставляти події.

Видалення ключа не видаляє підписників, кампанії, теги, поля, сегменти, автоматизації або інші дані облікового запису. Воно видаляє облікові дані, які використовуються для доступу до підтримуваних кінцевих точок 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» усе ще відображається

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

Якщо створення не вдалося, перезавантажте сторінку, перш ніж повторювати спробу. Інша сторінка або налаштування автоматизації могли вже створити ключ облікового запису.

Ключ на сторінці виглядає надто коротким

Сторінка навмисно показує лише перші п’ять символів і *****. Натисніть «Copy», щоб скопіювати повне значення. Не надсилайте замаскований текст у запиті.

«Copy» не змінюється на «Copied!»

Браузер міг заблокувати доступ до буфера обміну. Залиште сторінку в активній вкладці, надайте доступ до буфера обміну, якщо з’явиться запит, і натисніть «Copy» ще раз.

Не намагайтеся відновити ключ із замаскованого тексту.

Запит повертає 401 Unauthorized

Перевірте, що:

• Назва заголовка точно X-API-Key.
• Заголовок містить повне значення без видимих зірочок.
• Інтеграція не надсилає натомість Authorization: Bearer.
• До секрету не додано пробіли, лапки або символ нового рядка.
• Ніхто не ротував і не видаляв ключ облікового запису.
• Службу перезапущено, якщо вона читає змінні середовища лише під час запуску.
• Запит надсилається до правильного середовища API Maildroppa.

Одна інтеграція працює, а інша припинила роботу після ротації

Ймовірно, друга інтеграція все ще використовує старий ключ. Періоду перекриття немає. Оновіть її секрет і перезапустіть процес, який кешує конфігурацію.

Сторінка 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-інтеграцію, підключену до облікового запису. Створюйте ключ лише за потреби, зберігайте його на надійних серверах і плануйте ротацію як зміну облікових даних усього облікового запису.