주 콘텐츠로 건너뛰기

주소록 API 사용하기

스티비
  • 업데이트 시간

💬 이 내용은 스탠다드 요금제에 해당하는 도움말입니다.

 

*이 문서에서는 주소록 API를 사용해 스티비 주소록과 운영하고 있는 DB를 연동하는 방법에 대한 기술적인 설명을 담고 있습니다.

 

들어가기 전에

주소록 API에 대한 요청 및 응답 방법은 스티비 API 문서에서 확인하고 테스트해볼 수 있습니다. API를 사용하면 스티비의 구독자 정보와 내 서비스의 사용자 정보를 연동하는 등 확장된 기능을 경험할 수 있습니다. 주소록 API는 주소록 웹훅과 함께 사용하면 더욱 강력한 기능이 됩니다.

목차

API 키 만들기

API 요청 및 응답 모델

공통

구독

완전삭제

수신거부

그룹 할당

그룹 해제

API 요청 및 응답 예제

 

API 키 만들기

주소록 API를 사용하려면 우선 스티비에서 API 키를 만들어야 합니다. API는 계정 단위로 관리되기 때문에 API 키의 생성과 관리는 모두 화면 오른쪽 위에 있는 [프로필(👤) → 계정 및 결제 → API 키] 에서 이루어집니다.

 

[새로 만들기]를 클릭해 API 키를 생성한 뒤, API 키 옆의 [복사하기]를 클릭하면 API 키를 복사할 수 있습니다. 이 키는 API 요청 시 토큰으로 사용됩니다. (API 키는 최대 10개까지 생성이 가능합니다.)

 

API 키가 노출되면 스티비 계정 보안에 치명적인 문제가 생길 수 있으니 주의하세요. 만약 노출이 의심되면 계정 API 키에서 해당 키를 비활성화하거나 삭제하고 새로운 키를 만드세요.

API로 제공되는 기능은 다음과 같습니다.

  • 구독: 주소록에 구독자를 추가합니다.

  • 수신거부: 구독자를 수신거부 상태로 변경합니다.

  • 완전삭제: 구독자를 완전삭제합니다. 구독자 정보와 활동 기록이 모두 삭제됩니다. 삭제된 구독자 정보와 활동 기록은 복구할 수 없습니다.

  • 그룹 할당: 구독자를 주소록의 특정 그룹에 추가합니다. (2018년 9월 26일 업데이트)

  • 그룹 해제: 구독자를 주소록의 특정 그룹에서 삭제합니다. (2018년 9월 26일 업데이트)

(API로 제공되는 기능은 계속 추가될 예정입니다.)

API는 주소록 웹훅과 함께 활용하면 스티비의 주소록의 상태와 사용자 서버의 고객 정보를 동기화할 수 있습니다.

API 요청 및 응답 모델

API에 대한 요청 및 응답 방법은 스티비 API 문서에서 확인하고 테스트해볼 수 있습니다.

API 요청 및 응답은 JSON 형식을 따릅니다. 예를 들어, 주소록에 구독자를 추가하려면 POST Method로 다음과 같은 JSON 형식의 요청을 보냅니다. API 요청에 대한 정책은 아래와 같이 운영하고 있습니다.

  • API 요청은 1초당 10회로 제한됩니다.
  • API 요청은 1회당 256KB로 제한됩니다. 구독자 추가 시 약 2,000명을 한 번에 추가할 수 있는 사이즈입니다. 사용자 정의 필드 값에 따라 달라질 수 있습니다.

공통

  • AccessToken: API 키

  • Content-Type: application/json

구독

listId(주소록에 할당된 고유의 아이디)는 아래 방법으로 확인할 수 있습니다.

  1. 주소록 목록에서 주소록 이름을 클릭하여 “주소록 대시보드"로 이동

  2. 브라우저에 표시되는 URL에서 "lists" 뒤의 숫자를 확인

Request Body

  • eventOccuredBy: 구독자를 추가한 방법을 구분합니다.
    - "MANUAL": 관리자에 의해 추가한 것으로 기록합니다. (기본값)
    - "SUBSCRIBER": 구독자가 직접 구독한 것으로 기록합니다.

  • confirmEmailYN: 구독 확인 이메일 발송 여부를 구분합니다.
    - "Y": 구독자에게 구독 확인 이메일을 발송하고, 구독자가 이 메일을 통해 구독 확인을 해야 구독자로 추가됩니다. 이 때 한 번에 추가하는 구독자가 10명을 초과하면 추가되지 않습니다.
    - "N": 구독 확인 과정없이 바로 구독자로 추가됩니다. (기본값)

  • groupIds: 그룹에 할당된 고유의 아이디(groupId)입니다. 해당 그룹에 구독자를 할당하여 추가합니다. (기본값: 할당 안 함.)

  • subscribers: 구독자 정보를 담고 있습니다. Key-Value 배열 형식으로 구성됩니다. 주소록 사용자 정의 필드에 정의된 내용을 따릅니다.
    - Key: Key: 사용자 정의 필드의 "태그"(email, name 등)
    - Value: Key에 해당하는 값

  • Key에 "$ad_agreed" 필드를 사용해 광고성 정보 수신동의 여부를 구분한다.
      • "Y": 광고성 정보 수신 여부를 '동의함'으로 추가합니다.
      • "N": 광고성 정보 수신 여부를 '동의하지 않음'(빈 값)으로 추가합니다.
    • "$ad_agreed" 필드를 사용하지 않거나 잘못된 값이 입력된 경우 ‘동의하지 않음’(빈 값)으로 추가합니다. 이때 이미 등록된 구독자의 광고성 정보 수신 동의 여부는 업데이트하지 않습니다.

추가 요청한 구독자가 주소록에 이미 존재하는 이메일 주소인 경우, eventOccuredBy 값과 구독자의 구독 상태에 따라 아래와 같이 처리됩니다.

  • eventOccuredBy가 MANUAL일 때: 이메일 주소, 이름 등의 구독자 정보를 업데이트합니다. 이 때 구독자의 구독 상태(예. 구독 중, 수신거부)는 변경되지 않습니다.

  • eventOccuredBy가 SUBSCRIBER일 때: 구독자의 구독 상태에 따라 다르게 처리됩니다.
    - 구독 중 상태일 때: 구독자 정보를 업데이트하지 않습니다. 기존 정보가 그대로 유지됩니다.
    - 수신거부 또는 자동삭제 상태일 때: 구독자의 구독 상태를 구독 중으로 변경하고 이메일 주소, 이름 등의 구독자 정보를 업데이트합니다.

주소록 웹훅으로 "구독" 이벤트 알림을 받기로 한 경우, "confirmEmailYN"이 "Y"라면, 구독 확인까지 완료됐을 때 이벤트 알림을 받을 수 있습니다.

groupId(그룹에 할당된 고유의 아이디)는 아래 방법으로 확인할 수 있습니다.

  1. 주소록 목록에서 주소록 이름을 클릭하여 [주소록 대시보드]로 이동

  2. [그룹]을 클릭하여 그룹 목록으로 이동

  3. 그룹 이름을 클릭하여 그룹 필터링이 적용된 구독자 목록으로 이동

  4. 브라우저에 표시되는 URL에서 'subscribed' 뒤의 숫자를 확인

 

이에 대한 응답은 다음과 같습니다.

  • Ok: 요청에 대한 성공/실패 여부를 구분합니다. (true: 성공, false: 실패)

  • Error: 요청 실패 원인이 표시됩니다. 에러 코드와 에러 메시지가 표시됩니다.
    - code: 에러 코드
    - message: 에러 메세지

  • Value: 요청 성공 결과가 표시됩니다. 결과 유형별로 Key-Value 배열 형식으로 표시됩니다.
    - Key: 결과 유형
    - success: 구독자 추가 성공
    - update: 상태 외 정보 업데이트
    - failNoEmail: 구독자 추가 실패 - 이메일 주소 없음.
    - failExistEmail: 구독자 추가 실패 - 이미 구독 중인 이메일 주소
    - failExistPhone: 구독자 추가 실패 - 이미 구독 중인 전화번호
    - failWrongEmail: 구독자 추가 실패 - 이메일 주소 형식 오류
    - failWrongPhone: 구독자 추가 실패 - 전화번호 형식 오류
    - failDuplicatedEmail: 구독자 추가 실패 - 이메일 주소 중복 요청
    - failDuplicatedPhone: 구독자 추가 실패 - 전화번호 중복 요청
    - failUnknown: 구독자 추가 실패 - 알수 없는 오류
    - Value: Key에 해당하는 구독자 정보가 Key-Value 배열 형식으로 표시됩니다. [주소록] [사용자 정의 필드]에 정의된 내용을 참조합니다.
    - Key: 사용자 정의 필드의 "태그"(email, name 등)
    - Value: Key에 해당하는 값

 

완전삭제

listId(주소록에 할당된 고유의 아이디)는 아래 방법으로 확인할 수 있습니다.

  1. 주소록 목록에서 주소록 이름을 클릭하여 “주소록 대시보드"로 이동

  2. 브라우저에 표시되는 URL에서 "lists" 뒤의 숫자를 확인

 

Request Body

이에 대한 응답은 다음과 같습니다.

  • Ok: 요청에 대한 성공/실패 여부를 구분합니다. (true: 성공, false: 실패)

  • Error: 요청 실패 원인이 표시됩니다. 에러 코드와 에러 메시지가 표시됩니다.

  • Value: 요청 성공 결과가 표시됩니다. 결과 유형별로 Key-Value 배열 형식으로 표시됩니다.
    - "success": 구독자 완전삭제 성공 리스트
    - "fail": 구독자 완전삭제 실패 리스트

 

수신거부

listId(주소록에 할당된 고유의 아이디)는 아래 방법으로 확인할 수 있습니다.

  • 주소록 목록에서 주소록 이름을 클릭하여 “주소록 대시보드"로 이동

  • 브라우저에 표시되는 URL에서 "lists" 뒤의 숫자를 확인

Request Body

  • 구독자의 이메일 주소를 배열 형식으로 입력합니다. (예: ["user1@domain.com","user2@domain.com"])

이에 대한 응답은 다음과 같습니다.

  • Ok: 요청에 대한 성공/실패 여부를 구분합니다. (true: 성공, false: 실패)

  • Error: 요청 실패 원인이 표시됩니다. 에러 코드와 에러 메시지가 표시됩니다.

  • Value: 요청 성공 결과가 표시됩니다. 결과 유형별로 Key-Value 배열 형식으로 표시됩니다.
    - "success": 구독자 수신거부 성공 리스트
    - "failOrAlreadyUnsubscribe": 구독자 실패 또는 이미 수신거부 중 리스트

그룹 할당

listId(주소록에 할당된 고유의 아이디)는 아래 방법으로 확인할 수 있습니다.

  • 주소록 목록에서 주소록 이름을 클릭하여 “주소록 대시보드"로 이동

  • 브라우저에 표시되는 URL에서 "lists" 뒤의 숫자를 확인

groupId(그룹에 할당된 고유의 아이디)는 아래 방법으로 확인할 수 있습니다.

  1. 주소록 목록에서 주소록 이름을 클릭하여 [주소록 대시보드]로 이동

  2. [그룹]을 클릭하여 그룹 목록으로 이동

  3. 그룹 이름을 클릭하여 그룹 필터링이 적용된 구독자 목록으로 이동

  4. 브라우저에 표시되는 URL에서 'subscribed' 뒤의 숫자를 확인

Request Body

이에 대한 응답은 다음과 같습니다.

  • Ok: 요청에 대한 성공/실패 여부를 구분합니다. (true: 성공, false: 실패)

  • Error: 요청 실패 원인이 표시됩니다. 에러 코드와 에러 메시지가 표시됩니다.

 

그룹 해제

listId(주소록에 할당된 고유의 아이디)는 아래 방법으로 확인할 수 있습니다.

  1. 주소록 목록에서 주소록 이름을 클릭하여 “주소록 대시보드"로 이동

  2. 브라우저에 표시되는 URL에서 "lists" 뒤의 숫자를 확인

groupId(그룹에 할당된 고유의 아이디)는 아래 방법으로 확인할 수 있습니다.

  1. 주소록 목록에서 주소록 이름을 클릭하여 [주소록 대시보드]로 이동

  2. [그룹]을 클릭하여 그룹 목록으로 이동

  3. 그룹 이름을 클릭하여 그룹 필터링이 적용된 구독자 목록으로 이동

  4. 브라우저에 표시되는 URL에서 'subscribed' 뒤의 숫자를 확인

 

Request Body

이에 대한 응답은 다음과 같습니다.

  • Ok: 요청에 대한 성공/실패 여부를 구분합니다. (true: 성공, false: 실패)

  • Error: 요청 실패 원인이 표시됩니다. 에러 코드와 에러 메시지가 표시됩니다.

API에 대한 요청 및 응답 방법은 스티비 API 문서에서 확인하고 테스트해볼 수 있습니다.

API 요청은 1초당 10회, 1회당 256KB로 제한되어 있습니다.

 

API 요청 및 응답 예제

“gildong.go@stibee.com”, “dooly@stibee.com”을 구독 확인 과정 없이 추가할 경우, 다음과 같이 요청합니다.

POST https://api.stibee.com/v1/lists/{listId}/subscribers
[
    {
        "eventOccuredBy": "SUBSCRIBER",
        "confirmEmailYN": "N",
        "groupIds": [
         "{groupId}"
        ],
        "subscribers": [
            {
                "email": "gildong.go@stibee.com",
                "name": "고길동"
            },
            {
                "email": "dooly@stibee.com",
                "name": "둘리"
            }
        ]
    }
]

 

“gildong.go@stibee.com”은 정상적으로 추가됐고, “dooly@stibee.com”은 수신거부 상태여서 추가되지 않았다면, 이에 대한 응답은 다음과 같습니다.

{
    "Ok": true,
    "Error": null,
    "Value": {
        "failDeny": [
                {
                        "email": "gildong.go@stibee.com",
                        "name": "고길동"
                }
        ],
        "failUnknown": [],
        "failWrongEmail": [],
        "success": [
                {
                        "email": "dooly@stibee.com",
                        "name": "둘리"
                }
        ],
        "update": []
    }
}

 

이미 추가된 "dooly@stibee.com"의 정보를 변경하려면, "eventOccuredBy"를 "MANUAL"로 설정하여, 다음과 같이 요청합니다.

POST https://api.stibee.com/v1/lists/{listId}/subscribers
[
    {
        "eventOccuredBy": "MANUAL",
        "confirmEmailYN": "N",
        "groupIds": [
         "{groupId}"
        ],
        "subscribers": [
            {
                "email": "dooly@stibee.com",
                "name": "둘리"
            }
        ]
    }
]

 

이미 추가된 '구독중' 상태인 구독자를 "eventOccuredBy"="SUBSCRIBER"로 설정하여 추가 요청하면 추가가 되지 않습니다. 이에 대한 응답은 다음과 같습니다.

{
    "Ok": false,
    "Error":
        {
            "Code": "LIST_ALREADY_SUBSCRIBED",
            "HttpStatusCode": 0,
            "Message": "이미 구독 중인 이메일 주소입니다."
        },
    "Value": null
}

관련 문서