API 키 생성 및 관리

게시일: 2026년 7월 16일 · 최종 업데이트: 2026년 9월 12일 · 작성자 Marcus Biel

API 키 페이지에서는 외부 시스템이 계정에서 지원되는 Maildroppa API 엔드포인트에 인증을 거쳐 접근할 수 있도록 키를 관리합니다.

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

API 키는 Maildroppa 계정을 대표하는 인증 정보입니다. 비밀번호처럼 취급하세요. 키를 입수한 사람은 키가 교체되거나 삭제될 때까지 해당 키로 접근할 수 있는 API 엔드포인트를 호출할 수 있습니다.

API 키의 용도

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

대표적인 활용 사례는 다음과 같습니다.

• CRM, 쇼핑몰, 멤버십 시스템 또는 내부 데이터베이스와 구독자 동기화
• 서버 측 애플리케이션에서 구독자 생성 또는 업데이트
• 지원되는 엔드포인트를 통한 태그, 필드, 필드 값 및 세그먼트 조회 또는 관리
• 자동화의 API 요청 트리거로 사용자 지정 이벤트 전송
• API를 통한 트랜잭션 이메일 메시지 발송
• 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” 기능을 사용할 수 있습니다.
• “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에 자동으로 포함되는 것은 아닙니다.

지원되는 고객용 API는 OpenAPI 문서에서 확인할 수 있습니다. API 키 사용이 문서화되지 않은 경로에는 키로 접근할 수 있다고 가정하지 마세요.

API 키 페이지에는 권한 범위나 엔드포인트별 권한을 설정하는 확인란이 없습니다. 따라서 연동 하나가 단일 엔드포인트만 사용하더라도 현재 계정 키는 보안상 중요한 인증 정보로 취급해야 합니다.

요청 횟수 제한

현재 OpenAPI 명세에 명시된 API 키의 요청 횟수 제한은 다음과 같습니다.

• 기본 고객용 API: 분당 300건, 시간당 2,000건
• /events의 Events API: 초당 100건, 버스트 허용량 500건

이 제한은 키를 공유하는 각 스크립트에 개별적으로 적용되는 것이 아니라 Maildroppa 계정에 적용됩니다. 따라서 여러 연동이 동일한 허용량을 함께 사용할 수 있습니다.

Maildroppa가 429 Too Many Requests를 반환하면 새 요청 전송을 중단하고, 응답에 Retry-After 헤더가 있으면 해당 지침을 따르세요. 여러 요청을 동시에 재시도하지 말고 큐에 넣어 관리하면서 재시도 간격을 조절하는 백오프를 사용하세요.

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

자동화 API 요청에 키 사용하기

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

“API request” 트리거를 설정할 때 Maildroppa는 이 페이지에서 관리하는 것과 동일한 계정 API 키를 사용합니다. 키가 없으면 트리거 설정에서 생성할 수 있으며, 전체 키가 포함된 미리 작성된 curl 요청을 복사할 수 있습니다.

이에 따라 다음 두 가지 사항에 유의해야 합니다.

• 계정 키를 교체하거나 삭제하면 자동화에 사용자 지정 이벤트를 보내는 시스템도 영향을 받습니다.
• 자동화 요청 예시를 복사하면 화면에서 키가 마스킹되어 있더라도 클립보드에는 비밀 값이 포함됩니다.

키를 교체하거나 삭제하기 전에 모든 API 요청 트리거와 외부 이벤트 전송 시스템을 연동 목록에 포함하세요.

API 키 재설정 또는 교체하기

현재 인증 정보를 재설정하거나 교체하려면 “Rotate API key”를 사용하세요. Maildroppa는 한 번의 작업으로 새 키를 생성하고 이전 키를 무효화합니다.

다음과 같은 경우 키를 교체하세요.

• 키가 노출되었을 가능성이 있는 경우
• 키를 알고 있던 사람이나 서비스 제공업체가 더 이상 접근할 필요가 없는 경우
• 보안 정책에 따라 인증 정보를 정기적으로 교체해야 하는 경우
• 오래되었거나 안전하지 않은 위치에 저장된 키를 교체하려는 경우

마스킹된 키 아래의 “Rotate API key”를 클릭하세요. 기존 키를 더 이상 사용할 수 없다는 경고 대화 상자가 열립니다.

계속하려면 대화 상자에서 “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”를 클릭하세요. 키가 계정에서 영구적으로 제거된다는 경고 대화 상자가 열립니다.

삭제하려면 대화 상자에서 “Delete API key”를 클릭하세요. 키를 유지하려면 “Cancel”을 클릭하세요.

삭제 후에는 다음과 같이 변경됩니다.

• 현재 키를 즉시 사용할 수 없게 됩니다.
• 페이지가 “No API key yet” 상태로 돌아갑니다.
• 삭제된 키를 사용하는 서버 연동은 더 이상 인증할 수 없습니다.
• 해당 키를 사용하는 자동화 API 요청 전송 시스템은 더 이상 이벤트를 전달할 수 없습니다.

키를 삭제해도 구독자, 캠페인, 태그, 필드, 세그먼트, 자동화 또는 기타 계정 데이터는 삭제되지 않습니다. 지원되는 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”가 계속 표시됩니다

현재 계정에 키가 없는 상태입니다. 버튼을 한 번 클릭하고 요청이 완료될 때까지 기다리세요.

생성에 실패하면 다시 시도하기 전에 페이지를 새로고침하세요. 다른 페이지나 자동화 설정에서 이미 계정 키가 생성되었을 수 있습니다.

페이지에 표시된 키가 너무 짧아 보입니다

페이지에는 의도적으로 처음 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 연동에 영향을 줍니다. 키는 필요할 때만 생성하고 신뢰할 수 있는 서버에 보관하세요. 키 교체는 계정 전체의 인증 정보를 변경하는 작업으로 보고 계획하세요.