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

API를 사용하면 스티비의 구독자 정보와 내 서비스의 사용자 정보를 연동하는 등 확장된 기능을 경험할 수 있습니다.

주소록 API는 주소록 웹훅과 함께 사용하면 더욱 강력한 기능이 됩니다 💪🏼

1. API 키 만들기

API를 사용하려면 우선 스티비에서 API 키를 만들어야 합니다. API는 계정 단위로 관리되기 때문에 API 키의 생성과 관리는 모두 사용자 메뉴의 계정 > API 키에서 이루어집니다.

2. API 사용하기

계정 > API 키에서 API 키를 생성한 뒤, API 키 옆의 복사하기를 클릭하면 API 키를 복사할 수 있습니다. 이 키는 API 요청 시 토큰으로 사용됩니다.

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

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

  • 구독: 주소록에 구독자를 추가합니다.
  • 수신거부: 구독자를 수신거부 상태로 변경합니다.
  • 완전삭제: 구독자를 완전삭제합니다. 구독자 정보와 활동 기록이 모두 삭제됩니다. 삭제된 구독자 정보와 활동 기록은 복구할 수 없습니다.
  • 그룹 할당: 구독자를 주소록의 특정 그룹에 추가합니다. (2018년 9월 26일 업데이트)
  • 그룹 해제: 구독자를 주소록의 특정 그룹에서 삭제합니다. (2018년 9월 26일 업데이트)

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

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

3. API 요청 및 응답 모델

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

API 요청 및 응답은 JSON 형식을 따릅니다. 예를 들어, 주소록에 구독자를 추가하려면 POST Method로 다음과 같은 JSON 형식의 요청을 보냅니다.

* API 요청은 최대 256KB로 사이즈가 제한되어있습니다.
* 구독자 추가 시, 약 2,000명을 한 번에 추가할 수 있는 사이즈입니다. 사용자 정의 필드 값에 따라 다를 수 있습니다.

[공통]

Header

  • AccessToken: API 키
  • Content-Type: application/json

[구독]

HTTP Methods

  • POST

Endpoint URL

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

  • 주소록 목록에서 주소록 이름을 클릭하여 “주소록 대시보드"로 이동
  • 브라우저에 표시되는 URL에서 "lists" 뒤의 숫자를 확인

Request Body

  • eventOccuredBy: 구독자를 추가한 방법을 구분합니다.
  • confirmEmailYN: 구독 확인 이메일 발송 여부를 구분합니다.
  • subscribers: 구독자 정보를 담고 있습니다. Key-Value 배열 형식으로 구성됩니다. 주소록 > 사용자 정의 필드에 정의된 내용을 따릅니다.

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

  • Ok: 요청에 대한 성공/실패 여부를 구분합니다. (true: 성공, false: 실패)
  • Error: 요청 실패 원인이 표시됩니다. 에러 코드와 에러 메시지가 표시됩니다.
  • Value: 요청 성공 결과가 표시됩니다. 결과 유형별로 Key-Value 배열 형식으로 표시됩니다.

[완전삭제]

HTTP Methods

  • DELETE

Endpoint URL

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

  • 주소록 목록에서 주소록 이름을 클릭하여 “주소록 대시보드"로 이동
  • 브라우저에 표시되는 URL에서 "lists" 뒤의 숫자를 확인

Request Body

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

  • Ok: 요청에 대한 성공/실패 여부를 구분합니다. (true: 성공, false: 실패)
  • Error: 요청 실패 원인이 표시됩니다. 에러 코드와 에러 메시지가 표시됩니다.
  • Value: 요청 성공 결과가 표시됩니다. 결과 유형별로 Key-Value 배열 형식으로 표시됩니다.

[수신거부]

HTTP Methods

  • PUT

Endpoint URL

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

  • 주소록 목록에서 주소록 이름을 클릭하여 “주소록 대시보드"로 이동
  • 브라우저에 표시되는 URL에서 "lists" 뒤의 숫자를 확인

Request Body

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

  • Ok: 요청에 대한 성공/실패 여부를 구분합니다. (true: 성공, false: 실패)
  • Error: 요청 실패 원인이 표시됩니다. 에러 코드와 에러 메시지가 표시됩니다.
  • Value: 요청 성공 결과가 표시됩니다. 결과 유형별로 Key-Value 배열 형식으로 표시됩니다.

[그룹 할당]

HTTP Methods

  • POST

Endpoint URL

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

  • 주소록 목록에서 주소록 이름을 클릭하여 “주소록 대시보드"로 이동
  • 브라우저에 표시되는 URL에서 "lists" 뒤의 숫자를 확인

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

  • 주소록 목록에서 주소록 이름을 클릭하여 "주소록 대시보드"로 이동
  • "그룹"을 클릭하여 그룹 목록으로 이동
  • 그룹 이름을 클릭하여 그룹 필터링이 적용된 구독자 목록으로 이동
  • 브라우저에 표시되는 URL에서 "subscribed" 뒤의 숫자를 확인

Request Body

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

  • Ok: 요청에 대한 성공/실패 여부를 구분합니다. (true: 성공, false: 실패)
  • Error: 요청 실패 원인이 표시됩니다. 에러 코드와 에러 메시지가 표시됩니다.

[그룹 해제]

HTTP Methods

  • POST

Endpoint URL

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

  • 주소록 목록에서 주소록 이름을 클릭하여 “주소록 대시보드"로 이동
  • 브라우저에 표시되는 URL에서 "lists" 뒤의 숫자를 확인

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

  • 주소록 목록에서 주소록 이름을 클릭하여 "주소록 대시보드"로 이동
  • "그룹"을 클릭하여 그룹 목록으로 이동
  • 그룹 이름을 클릭하여 그룹 필터링이 적용된 구독자 목록으로 이동
  • 브라우저에 표시되는 URL에서 "subscribed" 뒤의 숫자를 확인

Request Body

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

  • Ok: 요청에 대한 성공/실패 여부를 구분합니다. (true: 성공, false: 실패)
  • Error: 요청 실패 원인이 표시됩니다. 에러 코드와 에러 메시지가 표시됩니다.

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

4. API 요청 및 응답 예제

hoyeol@slowalk.co.kr”, “hakjin@slowalk.co.kr”를 구독 확인 과정 없이 추가할 경우, 다음과 같이 요청합니다.

POST https://api.stibee.com/v1/lists/{listId}/subscribers
[
    {
        "eventOccuredBy": "SUBSCRIBER",
        "confirmEmailYN": "N",
        "subscribers": [
            {
                "email": "hakjin@slowalk.co.kr",
                "name": "학진"
            },
            {
                "email": "hoyeol@slowalk.co.kr",
                "name": "호열"
            }
        ]
    }
]

hoyeol@slowalk.co.k”는 정상적으로 추가됐고, “hakjin@slowalk.co.kr”는 수신거부 상태여서 추가되지 않았다면, 이에 대한 응답은 다음과 같습니다.

{
    "Ok": true,
    "Error": null,
    "Value": {
        "failDeny": [
                {
                        "email": "hakjin@slowalk.co.kr",
                        "name": "학진"
                }
        ],
        "failUnknown": [],
        "failWrongEmail": [],
        "success": [
                {
                        "email": "hoyeol@slowalk.co.kr",
                        "name": "호열"
                }
        ],
        "update": []
    }
}

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

POST https://api.stibee.com/v1/lists/{listId}/subscribers
[
    {
        "eventOccuredBy": "MANUAL",
        "confirmEmailYN": "N",
        "subscribers": [
            {
                "email": "hoyeol@slowalk.co.kr",
                "name": "임호열"
            }
        ]
    }
]

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

{
    "Ok": false,
    "Error":
        {
            "Code": "LIST_ALREADY_SUBSCRIBED",
            "HttpStatusCode": 0,
            "Message": "이미 구독 중인 이메일 주소입니다."
        },
    "Value": null
}
답변을 찾으셨나요?