API 키 생성 및 관리

Published: 2026년 7월 16일 · Last updated: 2026년 7월 21일 · By Marcus Biel

API 키 페이지에서는 외부 시스템이 계정에서 지원되는 Maildroppa API 엔드포인트에 인증된 방식으로 액세스할 수 있습니다.

API 키 하나를 생성하고, 전체 보안 값을 복사하고, 키를 교체하여 안전하게 재설정하거나, 더 이상 필요하지 않을 때 삭제할 수 있습니다. 동일한 계정 키를 서버 측 통합과 Maildroppa Automations의 API 요청 트리거에서 사용할 수 있습니다.

API 키는 Maildroppa 계정을 나타냅니다. 비밀번호처럼 취급하세요. 키를 얻은 사람은 키를 교체하거나 삭제할 때까지 해당 키에 사용 가능한 API 엔드포인트를 호출할 수 있습니다.

API 키의 용도

Maildroppa 외부의 소프트웨어가 대화형 사용자 로그인 없이 Maildroppa와 연동해야 할 때 API 키를 사용하세요.

일반적인 예는 다음과 같습니다.

• CRM, 쇼핑몰, 멤버십 시스템 또는 내부 데이터베이스와 구독자를 동기화합니다.
• 서버 측 애플리케이션에서 구독자를 생성하거나 업데이트합니다.
• 지원되는 엔드포인트를 통해 태그, 필드, 필드 값 및 세그먼트를 읽거나 관리합니다.
• Automation의 API 요청 트리거로 사용자 지정 이벤트를 전송합니다.
• API를 통해 트랜잭션 Email Messages를 전송합니다.
• API 기반 웹훅 구독을 관리합니다.

API 키는 서버 간 통신을 위한 것입니다. 방문자의 브라우저, 공개 웹사이트, 모바일 애플리케이션 또는 임베드된 가입 양식에서 실행되는 코드에는 적합하지 않습니다.

현재 페이지에는 “beta” 표시가 있습니다. API에서 현재 지원되는 엔드포인트, 요청 본문, 매개변수 및 응답 스키마는 연결된 OpenAPI 문서를 기준으로 확인하세요.

API 키 페이지 열기

“Settings”를 열고 “Developers”를 확장한 다음 “API key”를 선택하세요.

다음 주소에서 페이지를 직접 열 수도 있습니다.

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

페이지에는 다음 항목이 포함됩니다.

• beta 배지가 있는 API 키 패널
• “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는 두 번째 키를 생성하지 않습니다. 기존 키를 사용하거나 교체하세요.

마스킹된 키 이해하기

페이지에서는 전체 보안 값을 일반 텍스트로 표시하지 않습니다. 처음 5개 문자를 표시한 뒤 별표 5개를 표시합니다. 예를 들면 다음과 같습니다.

a1b2c*****

이는 시각적 마스킹일 뿐입니다. 별표는 키의 실제 길이를 나타내지 않으며, 마스킹된 값은 API 요청에 사용할 수 없습니다.

“Copy”를 클릭하면 현재 전체 키가 클립보드에 기록됩니다. 복사에 성공하면 버튼이 잠시 “Copied!”로 변경됩니다.

페이지로 다시 돌아와도 키는 계속 마스킹되어 표시되지만, “Copy”는 현재 전체 값을 계속 복사합니다. 따라서 생성할 때 저장하지 않았다는 이유만으로 유효한 키를 교체할 필요는 없습니다.

키 안전하게 저장하기

복사한 키를 통합에 사용되는 보안 저장소로 바로 옮기세요.

적합한 위치는 다음과 같습니다.

• 관리형 보안 관리자
• 보호된 서버 환경 구성
• 암호화된 배포 보안 값
• 운영 복구에 사용하는 비밀번호 관리자

다음 위치에는 키를 저장하지 마세요.

• 브라우저 측 JavaScript 또는 다운로드 가능한 다른 프런트엔드 번들
• 저장소에 커밋된 공개 또는 비공개 소스 코드 파일
• URL 또는 쿼리 매개변수
• 공개 문서, 스크린샷, 지원 메시지 또는 이슈 트래커
• 공유 애플리케이션 로그, 분석 이벤트 또는 오류 보고서
• 암호화되지 않은 스프레드시트 또는 일반 팀 채팅

다른 사람이 문서나 공유된 셸 기록에 복사할 curl 예제에 키를 넣지 마세요. 대신 MAILDROPPA_API_KEY와 같은 환경 변수를 사용하세요.

API 키 사용하기

전체 키를 X-API-Key HTTP 요청 헤더에 전송하세요.

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

Bearer 토큰으로 전송하지 마세요. Maildroppa는 Authorization: Bearer ...가 아니라 X-API-Key를 요구합니다.

운영 API와 대화형 OpenAPI 문서는 다음에서 이용할 수 있습니다.

https://api.maildroppa.com

API 키 페이지에서 “View OpenAPI docs”를 클릭하면 새 브라우저 탭에서 문서가 열립니다. 그곳에서 엔드포인트를 선택하여 메서드, 경로, 매개변수, 요청 본문, 응답 유형 및 가능한 상태 코드를 확인하세요.

요청 예시

다음 예시는 구독자의 첫 번째 페이지를 가져옵니다. 명령에 보안 값을 직접 넣는 대신 환경 변수에서 키를 읽습니다.

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

통합이 실행되는 보안 환경에서 변수를 설정하세요. 정확한 메서드, 경로, 쿼리 매개변수 및 본문은 엔드포인트에 따라 다릅니다. Maildroppa 애플리케이션에서 사용할 수 있는 작업을 보고 추측하지 말고 OpenAPI 문서에서 해당 세부 정보를 복사하세요.

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의 Events API: 초당 100건, 버스트 용량 500건

이 제한은 각 스크립트에 독립적으로 적용되는 것이 아니라 Maildroppa 계정에 적용됩니다. 따라서 여러 통합이 동일한 허용량을 함께 사용할 수 있습니다.

Maildroppa가 429 Too Many Requests를 반환하면 새 요청 전송을 중단하고, 응답에 Retry-After 헤더가 있으면 이를 준수하세요. 여러 병렬 재시도를 시작하지 말고 큐와 제어된 백오프를 사용하세요.

API가 beta 상태인 동안 요청 제한 정책은 변경될 수 있습니다. 대량 통합을 설계하기 전에 OpenAPI 문서 상단의 정보를 확인하세요.

Automation API 요청에 키 사용하기

시스템에서 Maildroppa의 Events API로 사용자 지정 이벤트를 보내면 Automation을 시작할 수 있습니다.

“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”를 클릭하여 새 자격 증명을 만들 수 있습니다. 삭제된 값은 복원되지 않습니다. 새 키를 사용하려면 모든 통합을 업데이트해야 합니다.

재설정 또는 삭제: 무엇을 선택해야 할까요?

새 자격 증명으로 API 액세스를 계속해야 한다면 “Rotate API key”를 선택하세요.

적어도 당분간 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 설정에서 이미 계정 키를 생성했을 수 있습니다.

페이지의 키가 너무 짧아 보입니다

페이지에는 의도적으로 처음 5개 문자와 *****만 표시됩니다. “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 통합에 영향을 줍니다. 필요할 때만 키를 생성하고, 신뢰할 수 있는 서버에 보관하며, 계정 전체의 자격 증명 변경으로서 교체를 계획하세요.